تشغيل أي مهارة في Manus بنقرة واحدة

p5-phone

النجوم٨

التفرعات٠

آخر تحديث٢٣ يوليو ٢٠٢٦ في ١٦:٠٩

Use when generating p5-phone examples or answering questions about p5-phone APIs: mobile sensors, device orientation, accelerometer, gyroscope, touch, microphone, p5.sound, speech recognition, PhoneCamera, ML5 camera mapping, vibration, torch/flashlight, NFC, Bluetooth BLE, GPS/geolocation, geoDistance/geoInPolygon, lockGestures, enablePermissionsTap, enableHardwareTap, arbitrary hardware combinations, mobile browser permissions, p5.js 2 compatibility.

التثبيت

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

تشغيل في Manus

المصدر

npuckett

npuckett/p5-phone

فتح مستودع GitHub عرض مستودعات المنشئ

تنزيل

تشغيل في Manus

المهن ذات الصلةSOC

استنادا إلى تصنيف SOC المهني

مطوّرو البرمجياتمهن الحاسوب والرياضيات·SOC 15-1252

SKILL.md

readonly

المزيد من هذا المستودع

نفس المستودع

Use whenever writing, editing, or reviewing p5.js sketches — p5.js is transitioning from 1.x to 2.x (2.x becomes the editor default in 2026), and models default to outdated 1.x patterns (preload(), curveVertex, keyCode, TypedDict) unless corrected. Trigger this for ANY p5.js code generation, even simple sketches, and especially for anything involving asset loading, custom shapes/curves, keyboard/mouse events, text measurement, or vector/array helper functions. Also trigger if the user mentions "p5", "p5.js", "creative coding sketch", or asks to convert/upgrade a sketch to p5.js 2.0.

2026-07-228

تشغيل أي مهارة بنقرة واحدة

name	p5-phone
description	Use when generating p5-phone examples or answering questions about p5-phone APIs: mobile sensors, device orientation, accelerometer, gyroscope, touch, microphone, p5.sound, speech recognition, PhoneCamera, ML5 camera mapping, vibration, torch/flashlight, NFC, Bluetooth BLE, GPS/geolocation, geoDistance/geoInPolygon, lockGestures, enablePermissionsTap, enableHardwareTap, arbitrary hardware combinations, mobile browser permissions, p5.js 2 compatibility.
argument-hint	Describe the p5-phone example or API question

p5-phone: Mobile Hardware for p5.js

p5-phone is a single-file helper library that gives p5.js sketches access to mobile phone hardware — motion sensors, microphone, sound, speech, camera (with ML5 coordinate mapping), vibration, torch/flashlight, NFC, GPS/geolocation, and Bluetooth LE — plus mobile gesture locking, browser-permission activation UI, and an on-screen debug console. Current version: 1.14.0.

It works in both p5.js 1.x and 2.x (auto-detected at runtime). Every public function is attached to window (global mode) and mirrored on p5.prototype (instance mode), so you call them as bare globals like lockGestures() and enableSensorTap().

Pair this with the p5js-2x skill. p5-phone only unlocks the hardware and hands you p5's own globals and objects; the p5.js 2.x language patterns around them (async asset loading, the unified pointer/touch model, renamed APIs) live in the p5js-2x skill. Load both when writing phone sketches — and read the next section before writing any hardware code.

When to use this skill

Use it whenever the request involves a p5-phone sketch, mobile p5.js hardware interaction, or an explanation of how p5-phone works: device orientation / accelerometer / gyroscope, touch, microphone / p5.sound, speech recognition, PhoneCamera and ML5 mapping, vibration, torch/flashlight, NFC, GPS/geolocation (geoRead, geoDistance, geoInPolygon), Bluetooth BLE, lockGestures, enablePermissionsTap / enableHardwareTap, arbitrary hardware combinations, mobile browser permissions, or p5.js 2 compatibility.

Quick Start

For generated examples, produce a complete index.html and sketch.js unless the user asks for a single file or snippet.

HTML baseline (p5.js 2-compatible):

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Mobile p5.js App</title>
  <style>
    body { margin: 0; padding: 0; overflow: hidden; }
  </style>
  <script src="https://cdn.jsdelivr.net/npm/p5@2.2.3/lib/p5.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/p5.js-compatibility@0.2.0/src/preload.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/p5-phone@1.12.1/dist/p5-phone.min.js"></script>
</head>
<body>
  <script src="sketch.js"></script>
</body>
</html>

Add p5.sound only when the sketch uses microphone levels, oscillators, audio input, sound output, or speech. Place it after p5 and before p5-phone/sketch.js:

<script src="https://cdn.jsdelivr.net/npm/p5.sound@0.3.0/dist/p5.sound.min.js"></script>

Minimal sketch (sketch.js):

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  enableSensorTap('Tap to enable motion sensors');
}

function draw() {
  background(20);
  if (!window.sensorsEnabled) {
    fill(255);
    textAlign(CENTER, CENTER);
    text('Waiting for sensors', width / 2, height / 2);
    return;
  }
  // rotationX / rotationY / rotationZ are p5.js built-ins, live once sensorsEnabled is true.
  fill(0, 180, 255);
  circle(width / 2 + rotationY * 4, height / 2 + rotationX * 4, 80);
}

function mousePressed() {
  return false; // let p5-phone's gesture handling manage the touch
}

Golden Rules

Call lockGestures() in every mobile sketch setup(). It blocks pull-to-refresh, swipe-back, pinch-zoom, double-tap zoom, long-press menus, and overscroll so the canvas behaves like an app.
Request every permission from a user gesture. iOS grants sensitive APIs only during transient user activation (a tap/click). Never auto-request on page load — use an enable* activation UI.
Gate all hardware reads behind the matching window.*Enabled flag (sensorsEnabled, micEnabled, bleConnected, etc.). Reading before permission returns stale/undefined data.
Use mousePressed / mouseDragged / mouseReleased, not p5 1.x touchStarted / touchMoved / touchEnded. The mouse callbacks fire for both mouse and touch in p5.js 1.x and 2.x; the touch callbacks are removed/no-ops in p5.js 2.
Serve over HTTPS (or localhost). Sensors, mic, camera, NFC, BLE, GPS, and torch all require a secure context on mobile.
Need several hardware features from one tap? Use a single combined call — enablePermissionsTap(['sensors', 'torch']) — not several single-permission binds on the same gesture. One call keeps iOS transient activation intact and fires userSetupComplete() once.
Use exactly one activation style per permission need unless the user explicitly asks to compare styles.

Use p5.js built-ins — do not reimplement them

The most common failure mode is a model hand-rolling hardware plumbing (a raw DeviceOrientationEvent listener, a touchstart handler, a Web Audio graph, a manual asset loader) instead of reading the values p5-phone and p5.js already provide. p5-phone deliberately surfaces everything through p5's own globals and objects. For each concern below, use the p5 built-in — never a bespoke equivalent:

p5-phone concern	Use these p5.js built-ins (not custom code)	Notes
Device orientation	`rotationX`, `rotationY`, `rotationZ` (+ `pRotationX/Y/Z`)	p5 globals; p5-phone only gates them via `sensorsEnabled`
Acceleration	`accelerationX/Y/Z`, `pAccelerationX/Y/Z`	p5 globals
Rotation rate	`rotationRateAlpha`, `rotationRateBeta`, `rotationRateGamma`	p5 globals
Motion events / thresholds	`deviceMoved()`, `deviceShaken()`, `setMoveThreshold()`, `setShakeThreshold()`, `deviceOrientation`	define the callbacks as globals
Touch / pointer input	`mousePressed()`, `mouseDragged()`, `mouseReleased()`, `mouseX`, `mouseY`, `touches[]`	p5.js 2 unifies mouse+touch under the pointer model; use `touches[]` for multitouch. Do not add your own `addEventListener('touchstart', …)`
Drawing the camera feed	`image(cam, x, y, w, h)` + `cam.mapKeypoint()/mapBox()`	`PhoneCamera` integrates with p5's `image()`; map ML5 results with its helpers, not manual video compositing
Microphone level / analysis	`p5.AudioIn`, `p5.Amplitude`, `p5.FFT` (p5.sound)	not a raw Web Audio graph
Generated sound	`p5.Oscillator`, `p5.Envelope` (p5.sound)	prefer over `loadSound()` for portability
Loading images/audio/JSON/font	`await loadImage()/loadSound()/loadJSON()/loadFont()` in `async setup()`	p5.js 2: `load*` return Promises — no `preload()`. See the `p5js-2x` skill
Mapping / ranges	`map()`, `constrain()`, `lerp()`	p5 math helpers

Two specific traps worth calling out:

Motion values are p5.js built-ins, not p5-phone APIs. p5-phone only requests the permission and sets window.sensorsEnabled. The data (rotationX, accelerationX, deviceShaken(), …) comes straight from p5.js. Do not invent p5-phone getters for them.
There is no bleValue() getter. Read incoming BLE data from window.bleValues[name] or from the bleReceive(name, value) callback. bleValues is an object keyed by characteristic name.

Permissions model

Every hardware family exposes the same six activation styles. Pick one:

Tap — enable<Feature>Tap(message) — full-screen tap overlay with a frosted message box.
Button — enable<Feature>Button(buttonText, statusText?) — auto-generated button.
Canvas — enable<Feature>Canvas(message) — prompt drawn on the p5 canvas.
Banner — enable<Feature>Banner(message, position?) — animated slide-in banner (position = 'top'/'bottom').
Minimal — enable<Feature>Minimal(messageOrOpts?, opts?) — bare semi-transparent full-screen overlay with an optional radiating circular icon. Cleaner than Tap; adjustable { color, opacity, icon, iconColor, iconSize }.
On (custom element) — enable<Feature>On(selector) — bind activation to any existing HTML element by CSS selector.

Full matrix:

Feature	Tap	Button	Canvas	Banner	Minimal	On (selector)
Motion sensors	`enableSensorTap(msg)`	`enableSensorButton(text)`	`enableSensorCanvas(msg)`	`enableSensorBanner(msg)`	`enableSensorMinimal(msg\|opts)`	`enableSensorOn(sel)`
Microphone	`enableMicTap(msg)`	`enableMicButton(text)`	`enableMicCanvas(msg)`	`enableMicBanner(msg)`	`enableMicMinimal(msg\|opts)`	`enableMicOn(sel)`
Sound output	`enableSoundTap(msg)`	`enableSoundButton(text)`	`enableSoundCanvas(msg)`	`enableSoundBanner(msg)`	`enableSoundMinimal(msg\|opts)`	`enableSoundOn(sel)`
Speech	`enableSpeechTap(msg)`	`enableSpeechButton(text)`	`enableSpeechCanvas(msg)`	`enableSpeechBanner(msg)`	`enableSpeechMinimal(msg\|opts)`	`enableSpeechOn(sel)`
Vibration	`enableVibrationTap(msg)`	`enableVibrationButton(text)`	`enableVibrationCanvas(msg)`	`enableVibrationBanner(msg)`	`enableVibrationMinimal(msg\|opts)`	`enableVibrationOn(sel)`
Torch / flashlight	`enableTorchTap(msg)`	`enableTorchButton(text)`	`enableTorchCanvas(msg)`	`enableTorchBanner(msg)`	`enableTorchMinimal(msg\|opts)`	`enableTorchOn(sel)`
NFC	`enableNfcTap(msg)`	`enableNfcButton(text)`	`enableNfcCanvas(msg)`	`enableNfcBanner(msg)`	`enableNfcMinimal(msg\|opts)`	`enableNfcOn(sel)`
GPS / geolocation	`enableGeoTap(msg)`	`enableGeoButton(text)`	`enableGeoCanvas(msg)`	`enableGeoBanner(msg)`	`enableGeoMinimal(msg\|opts)`	`enableGeoOn(sel)`
Bluetooth (BLE)	`enableBleTap(opts?)`	`enableBleButton(opts?)`	`enableBleCanvas(opts?)`	`enableBleBanner(opts?)`	`enableBleMinimal(opts?)`	`enableBleOn(sel)`
Camera	`enableCameraTap(msg)`	`enableCameraButton(text)`	`enableCameraCanvas(msg)`	`enableCameraBanner(msg)`	`enableCameraMinimal(msg\|opts)`	`enableCameraOn(sel)`
Sensors + mic	`enableAllTap(msg)`	`enableAllButton(text)`	`enableAllCanvas(msg)`	`enableAllBanner(msg)`	`enableAllMinimal(msg\|opts)`	`enableAllOn(sel)`
Any combination	`enablePermissionsTap(list, msg)`	`enablePermissionsButton(list, text)`	`enablePermissionsCanvas(list, msg)`	`enablePermissionsBanner(list, msg)`	`enablePermissionsMinimal(list, msg\|opts)`	`enablePermissionsOn(sel, list)`

Notes:

enableBle* take an options object ({ label, message, statusText, position }), unlike the other families which take positional (message, position) / (buttonText, statusText).
enableGyro* is a legacy alias for enableSensor*. Prefer enableSensor* for new examples; use enableGyro* only to match older published sketches.
enableAll* is shorthand for sensors + mic. For any other mix, use enablePermissions*.
enableHardware* is an exact alias of enablePermissions*.
Minimal accepts the message as a string, as an options object, or both: enableSensorMinimal('Tap'), enableSensorMinimal({ opacity: 0.6, iconColor: '#fff' }), enableSensorMinimal('Tap', { color: '#000', icon: false }).

Activation style examples

The six styles differ only in how the unlock screen looks — the rest of the sketch is identical. Here is one simple tilt-a-ball sketch; swap the single enable* line to change the activation UI.

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  enableSensorCanvas('Tap the canvas to begin'); // <-- the only line that changes
}

function draw() {
  background(20);
  if (!window.sensorsEnabled) return;            // gate all hardware reads

  fill(80, 200, 255);
  noStroke();
  circle(width / 2 + rotationY * 3, height / 2 + rotationX * 3, 60);

  fill(255);
  textAlign(CENTER, TOP);
  textSize(16);
  text('Tilt your phone to move the ball', width / 2, 30);
}

What each unlock screen looks like (replace the marked line above):

Tap — enableSensorTap('Tap to enable motion sensors') — full-screen dark overlay with a centered frosted-glass message box.
Button — enableSensorButton('ENABLE MOTION SENSORS') — a centered gradient button (plus optional status text) over the idle canvas.
Canvas — enableSensorCanvas('Tap the canvas to begin') — no overlay; a text hint is drawn on the canvas until the first touch.
Banner — enableSensorBanner('Tap to enable motion sensors', 'bottom') — a slim slide-in bar pinned to the top or bottom.
Minimal — enableSensorMinimal('Tap to begin') — a bare semi-transparent full-screen tint with a small radiating white icon. Adjustable: enableSensorMinimal({ color: '#0a0', opacity: 0.4, iconColor: '#fff' }).
On (custom element) — enableSensorOn('#start-btn') — no built-in UI; activation is bound to an HTML element you add yourself (e.g. <button id="start-btn">Start</button>).

For styles 1–5 nothing else is required. For style 6, add the target element to your index.html; p5-phone waits for it and attaches the permission trigger. Each style has a matching enableMic*, enableSound*, enablePermissions*, etc. variant — the style suffix is interchangeable across all hardware families.

Combining features

enablePermissions* (a.k.a. enableHardware*) takes a list plus a message. The list can be an array or a space/comma string.

Canonical tokens: sensors, mic, sound, speech, vibration, torch, nfc, geo, camera.

Aliases (all normalized to the canonical tokens): sensor, motion, orientation, gyro, gyroscope, accelerometer → sensors; microphone, audioin → mic; audio, audiooutput, output → sound; voice, recognition → speech; vibrate, haptic, haptics → vibration; flashlight, flash, light → torch; tag, tags → nfc; gps, location, geolocation → geo; video, webcam → camera; all → sensors + mic.

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  enablePermissionsTap(['sensors', 'mic'], 'Tap to enable motion + microphone');
}

function draw() {
  if (!window.sensorsEnabled || !window.micEnabled) return;
  // Use motion values and microphone input here.
}

Desktop QR and device detection (dev helpers)

For the common dev workflow — open the sketch on desktop, then scan a QR to load it on the phone — call showDesktopQr() once in setup(). It renders a floating QR of the current page on desktop only and is a no-op on mobile, so you never have to generate or close a QR on the phone. It is decoupled from the enable functions and works with any activation style.

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  showDesktopQr();                     // floating QR, desktop only; nothing on phone
  enableSensorMinimal('Tap to begin'); // minimal overlay on both
}

showDesktopQr(options?) options: url (defaults to location.href), position ('top-right' default; also 'top-left'/'bottom-right'/'bottom-left'), size (px, default 180), label (caption, default "Scan to open on your phone"), closable (default true), rememberDismiss (default true — closing hides it for the session). hideDesktopQr() removes the panel; setQrUrl(url) updates the URL (or creates the panel). The QR lazily loads qrcodejs from a CDN only on desktop, so mobile sketches download nothing extra; if the CDN is blocked (strict CSP / offline) it warns and removes the panel.

Device detection is also exposed directly: window.isMobile and window.isDesktop (set once at load, best-effort from UA + coarse-pointer + touch signals, including the iPadOS-13+ Mac-UA case). Use them to branch dev-only UI.

Status variables and callbacks

Read these window.* flags before using hardware data:

Motion: sensorsEnabled
Microphone: micEnabled
Sound: soundEnabled
Speech: speechEnabled
Vibration: vibrationEnabled
Torch: torchEnabled, torchSupported, torchActive, torchError, torchCapability
NFC: nfcEnabled, nfcStatus, nfcError, nfcTagAliases, lastNfcSerialNumber, lastNfcAlias, lastNfcMessage
GPS: geoEnabled, geoStatus, geoError, lastGeoPosition
BLE: bleSupported, bleConnected, bleStatus, bleError, bleDeviceName, bleValues
Camera: cameraEnabled
Gestures: gesturesLocked

Callbacks your sketch can define (p5-phone calls them if present):

userSetupComplete() — fires once immediately after permissions succeed.
deviceMoved(), deviceShaken() — p5.js motion events (available after sensorsEnabled).
nfcRead(message, serialNumber) — a tag was read.
geoRead(position) — a new GPS position arrived. position is a plain object: { latitude, longitude, accuracy, altitude, altitudeAccuracy, heading, speed, timestamp }.
onGeoError(error) — a GPS stream error after the watch started. error.code: 1=PERMISSION_DENIED, 2=POSITION_UNAVAILABLE, 3=TIMEOUT.
bleReceive(name, value) — a BLE characteristic notified or was read.

function userSetupComplete() {
  debug('Permissions ready');
}

Motion sensors

After window.sensorsEnabled is true, read p5.js built-ins:

Orientation: rotationX, rotationY, rotationZ
Acceleration: accelerationX, accelerationY, accelerationZ
Rotational velocity: rotationRateAlpha, rotationRateBeta, rotationRateGamma
Events: deviceMoved(), deviceShaken()
Thresholds: setMoveThreshold(value), setShakeThreshold(value)
Orientation state: deviceOrientation

iOS requires the sensor permission to be requested from a tap/click. Never auto-request motion permission on page load.

Microphone and sound

Include p5.sound and create p5.AudioIn() before enabling mic. For simple examples read levels with mic.getLevel() after window.micEnabled is true. Avoid wiring p5.Amplitude.setInput(mic) before permission — p5.sound 0.3.0 can throw in p5.js 2 previews.

let mic;

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  mic = new p5.AudioIn();
  enableMicTap('Tap to enable microphone');
}

function draw() {
  background(0);
  if (!window.micEnabled) return;
  const level = mic.getLevel();
  circle(width / 2, height / 2, 40 + level * 600);
}

For generated audio, use enableSoundTap() (or enableSoundOn(selector)) to resume the AudioContext, then p5.Oscillator. Prefer generated sound over loadSound() unless the user provides audio assets — it is more portable in the p5 Web Editor.

Speech recognition

enableSpeech* satisfies the mobile audio/user-activation requirement and sets window.speechEnabled; it deliberately does not create a p5.AudioIn (which would conflict with the mic). After activation, create your own Web Speech API SpeechRecognition object.

Camera and ML5 (`PhoneCamera`)

createPhoneCamera(active = 'user', mirror = true, mode = 'fitHeight') returns a PhoneCamera. The camera is not initialized until an enableCamera* gesture (this fixes an iOS rotation bug).

active: 'user' (front) or 'environment' (rear).
mirror: mirror the display (front cameras usually true).
mode: 'fitHeight', 'fitWidth', 'cover', 'contain', or 'fixed'.

let cam;
let model;

function setup() {
  createCanvas(405, 720);
  lockGestures();
  cam = createPhoneCamera('user', true, 'fitHeight');
  enableCameraTap('Tap screen to enable camera');

  cam.onReady(async () => {
    model = await ml5.handPose({ maxHands: 1, runtime: 'mediapipe', flipped: false });
    model.detectStart(cam.videoElement, gotResults);
  });
}

PhoneCamera properties: ready, video (p5 element), videoElement (native <video> for ML5), width, height, active, mirror, mode, fixedWidth, fixedHeight.

Coordinate-mapping methods (video space → display space, mirror-aware):

cam.onReady(callback) — safe point to start ML5.
cam.getDimensions() → { x, y, width, height, scaleX, scaleY }.
cam.mapPoint(x, y) → { x, y }.
cam.mapKeypoint(keypoint) / cam.mapKeypoints(keypoints).
cam.mapBox(box) / cam.mapBoxes(boxes).
cam.remove() — stop and clean up the camera.

Set ML5 flipped: false when available — PhoneCamera already handles mirroring and coordinate mapping, so pass raw ML5 results through the map* helpers.

For ml5@1 with p5@2.2.3, add the preload-counter polyfill before loading ml5:

<script src="https://cdn.jsdelivr.net/npm/p5@2.2.3/lib/p5.js"></script>
<script src="https://cdn.jsdelivr.net/npm/p5.js-compatibility@0.2.0/src/preload.js"></script>
<script>
  p5.prototype._incrementPreload ||= function() {};
  p5.prototype._decrementPreload ||= function() {};
</script>
<script src="https://unpkg.com/ml5@1/dist/ml5.min.js"></script>

For Three.js pages that use ML5 but are not p5 sketches, put p5, the compatibility shim, the preload-counter polyfill, and ml5 in the document <head> so p5 Web Editor preview injection does not run before p5 exists.

NFC

Android Chrome only, requires HTTPS. Compatible with widely available NFC Type 2 tags — NTAG213, NTAG215, NTAG216 — and any NDEF-formatted tag.

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  enableNfcTap('Tap to enable NFC');
}

function nfcRead(message, serialNumber) {
  setNfcTagAlias(serialNumber, 'example-tag');
  debug('Read NFC tag: ' + serialNumber);
}

function draw() {
  background(20);
  if (isNfcTag('example-tag')) {
    background(0, 120, 255);
  }
}

Helpers: setNfcTagAlias(serialNumber, alias), getNfcTagAlias(serialNumber?) (defaults to window.lastNfcSerialNumber), isNfcTag(aliasOrSerialNumber), stopNfc(). Track state via window.nfcStatus (idle/starting/requesting-permission/scanning/tag-read/permission-denied/unsupported/secure-context-required/error/stopped) and window.nfcError.

GPS / geolocation

Cross-platform (iOS Safari + Android Chrome), requires HTTPS. Builds on navigator.geolocation — the only well-supported API in 2026. Coarse by default (battery-friendly, ~50-100m); opt into real GPS via setGeoOptions({ enableHighAccuracy: true }) before enabling. Cold start can take 5-30s.

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  // Optional: real GPS (~5-10m outdoors). Omit for coarse default.
  setGeoOptions({ enableHighAccuracy: true });
  enableGeoTap('Tap to enable GPS');
}

function draw() {
  background(20);
  const pos = window.lastGeoPosition;
  if (pos) {
    text(pos.latitude.toFixed(5) + ', ' + pos.longitude.toFixed(5), width / 2, height / 2);
  } else if (window.geoStatus === 'requesting-permission') {
    text('Acquiring GPS…', width / 2, height / 2);
  }
}

function geoRead(position) {
  // { latitude, longitude, accuracy, altitude, altitudeAccuracy, heading, speed, timestamp }
}

Helpers: setGeoOptions({ enableHighAccuracy?, timeout?, maximumAge? }) (call before enableGeo*), getGeoPosition() (sync last position or null), geoDistance(lat1, lon1, lat2, lon2, units) (Haversine; 'm' default, 'km', 'mi'), geoInPolygon([{lat,lon},…], {lat,lon}) (ray-casting geofence test), stopGeo(). Track state via window.geoStatus (idle/requesting-permission/active/permission-denied/unsupported/secure-context-required/error/stopped) and window.geoError. Optional error callback: onGeoError(error).

Gotchas: iOS does not track in background/locked screen; in-app browsers (Instagram/Facebook) usually fail — tell users to open in Safari; navigator.permissions.query({name:'geolocation'}) always returns 'prompt' on Safari (WebKit bug), so don't gate UI on it.

Bluetooth Low Energy (BLE)

Web Bluetooth exchanges typed values with Arduino-class peripherals. Call bleSetup() in setup() before any connect helper; connect from a user gesture via enableBle*.

Platform support:

Chrome/Edge on Android and desktop over HTTPS (or localhost).
iOS Safari/Chrome: not supported — use the Bluefy browser app.
Embedded iframes need allow="bluetooth".

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();

  bleSetup({
    namePrefix: 'p5phone',      // optional device-name filter
    autoReconnect: true,        // optional
    characteristics: [
      { name: 'temp', type: 'float', notify: true },
      { name: 'brightness', type: 'uint8', write: true }
    ]
  });

  enableBleButton({ label: 'Connect device' });
  showDebug();
}

function draw() {
  background(20);
  if (bleConnected) {
    text('temp: ' + (bleValues.temp ?? '—'), 20, 40);
  }
}

function mousePressed() {
  if (bleConnected) {
    bleWrite('brightness', floor(map(mouseX, 0, width, 0, 255)));
  }
  return false;
}

function bleReceive(name, value) {
  debug('BLE ' + name + ' = ' + value);
}

bleSetup(config) fields:

serviceUUID — hyphenated 128-bit UUID; defaults to the P5PhoneBLE service if omitted.
namePrefix — optional device-name filter.
autoReconnect — optional boolean.
characteristics — required array of { name, type, read?, write?, notify?, uuid? }. Each needs at least one of read/write/notify. Omit uuid to auto-derive it from the service UUID and declaration order (must match the P5PhoneBLE Arduino side). Names must be unique.

Valid type values: bool, int8, uint8, int16, uint16, int32, uint32, float, double, string, bytes. Numeric types use little-endian byte order.

Lifecycle and I/O:

enableBle*(options) — connect from a user gesture.
bleConnect() / bleDisconnect() — programmatic connect/disconnect (connect still needs a gesture).
bleRead(name) — async; reads and decodes a characteristic, updates window.bleValues[name], returns the value.
bleWrite(name, value, opts?) — async; opts.ack === false uses write-without-response (default is write-with-response). String writes over ~20 bytes may truncate on default-MTU peripherals.
isBleSupported() — boolean.
bleReceive(name, value) — your callback, fired on notify and on read.

window.bleStatus progresses through idle/connecting/connected/requesting/disconnected/error/unsupported. bleValues is not cleared on disconnect (sketches keep rendering last-known values).

Vibration

Use enableVibration* before vibrate(pattern). iOS does not support the Vibration API — write examples that still show useful feedback when window.vibrationEnabled is false.

function mousePressed() {
  if (window.vibrationEnabled) {
    vibrate([40, 30, 80]); // ms on / off / on, or a single number
  }
  return false;
}

stopVibration() cancels an ongoing pattern.

Torch / flashlight

Android-Chrome-oriented, requires HTTPS, works through a rear-camera stream. Enable with enableTorch*() (or enablePermissions*(['torch'])), then control the light:

torchOn(), torchOff(), toggleTorch(), setTorch(enabled) (async), stopTorch(), isTorchSupported().
Flashlight aliases: enableFlashlight*, flashlightOn(), flashlightOff(), toggleFlashlight(), setFlashlight(), stopFlashlight().

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  enablePermissionsTap(['sensors', 'torch'], 'Tap to enable shake flashlight');
}

async function deviceShaken() {
  if (window.sensorsEnabled && window.torchEnabled) {
    await toggleTorch();
  }
}

Keep flashing pulses slow and short, avoid rapid strobing, and call torchOff() or stopTorch() when the effect ends.

lockGestures reference

lockGestures(options?)

options:

mode — 'fullscreen' (default) or 'embedded'.
element — target element for embedded mode (defaults to the first <canvas>).
warnBeforeLeave — show a leave-confirmation prompt (default false).
trapHistory — trap back/forward navigation (default true in fullscreen, false in embedded).

Use bare lockGestures() for full-screen mobile sketches. Use lockGestures({ mode: 'embedded', element: canvas }) for a canvas embedded in a scrollable, multi-section page — it scopes gesture blocking to that canvas so the rest of the page still scrolls. unlockGestures() restores the saved handlers, listeners, and styles. window.gesturesLocked reflects the current state.

Caveat: p5 touch/mouse callbacks are snapshotted when gestures lock. If you assign window.mousePressed = ... after lockGestures(), you replace p5-phone's wrapper. Define your callbacks before locking, or reassign is fine as long as you return false from them.

Debug console

For on-device troubleshooting, call showDebug() once in setup(), then log:

debug(message), debugWarn(message), debugError(message)
hideDebug(), toggleDebug()

Most useful for camera, NFC, BLE, and permission troubleshooting. Use sparingly in finished examples.

Platform support matrix

Feature	iOS Safari	Android Chrome
Motion sensors	✓ (permission tap required)	✓ (no prompt)
Microphone	✓	✓
Sound output	✓	✓
Speech recognition	Web Speech API support varies	✓
Camera	✓	✓
Vibration	✗ (API absent)	✓
Torch / flashlight	✗	✓
NFC	✗	✓ (HTTPS)
GPS / geolocation	✓ (HTTPS, user gesture)	✓ (HTTPS, user gesture)
Bluetooth BLE	✗ (use Bluefy app)	✓ (HTTPS)

All hardware requires a secure context (HTTPS or localhost).

Troubleshooting

Permission never fires / *Enabled stays false — the request must run inside a user gesture. Confirm you used an enable* activation UI and did not call it on load. On iOS a single gesture only grants one activation window, so combine features with one enablePermissions* call.
ML5 throws about _incrementPreload / preload with p5@2.2.3 — add the preload-counter polyfill shim before loading ml5 (see Camera section).
Torch or NFC does nothing — both are Android-Chrome + HTTPS only; check window.torchSupported / window.nfcStatus.
GPS hangs on "Acquiring…" or times out — cold start can take 5-30s, longer indoors; move outdoors, retry, and confirm OS-level Location Services is on. window.geoStatus tells you which state you're in.
GPS denied even after tapping Allow — the OS-level Location Services toggle (iOS Settings → Privacy & Security → Location Services; Android Settings → Location) must also be on; in-app browsers (Instagram/Facebook) usually fail — open in Safari/Chrome.
BLE won't connect on iPhone — Web Bluetooth is unavailable in iOS Safari/Chrome; use the Bluefy app.
Touch callbacks never run — touchStarted/Moved/Ended are no-ops in p5.js 2; switch to mousePressed/mouseDragged/mouseReleased.
Mic example throws in preview — don't call p5.Amplitude.setInput(mic) before window.micEnabled; read mic.getLevel() after permission.

Answering questions

Explain the browser-permission reason, especially iOS transient user activation.
Distinguish sensors, mic, sound-only, speech, camera, vibration, torch, NFC, and GPS permissions.
Mention HTTPS requirements for mobile hardware.
Mention p5.js 2 event changes when touch callbacks are involved.
Flag browser/device limits clearly: torch and NFC are Android-Chrome-oriented; vibration is unsupported on iOS; BLE needs Bluefy on iOS; speech recognition depends on Web Speech API support.
Point to the bundled examples under examples/ when useful — feature folders include movement/, microphone/, sound/, touch/, vibration/, camera/, torch/, nfc/, geo/, ble/, and combined/, plus ml5/, UIStyles/, and UXcompare/.
When migrating examples to the p5 Web Editor, follow the web-editor batch-sync workflow in docs/web-editor/ and record links in webeditorLinks.md.

Example quality checklist

Before finishing generated code, confirm:

lockGestures() is called in setup().
The permission request happens from a user-activation path (tap, button, banner, canvas, or custom element).
Hardware data is read only after the matching window.*Enabled flag is true.
The HTML includes the needed dependencies and no unused heavy libraries.
p5.js 2-compatible mouse* callbacks are used (not p5 1.x touch callbacks).
Text and canvas output fit mobile screens.
Asset-dependent examples either include the assets or clearly document that the user must upload them.
ML5 camera examples include the p5 2 compatibility shim and use PhoneCamera mapping helpers.

name	p5-phone
description	Use when generating p5-phone examples or answering questions about p5-phone APIs: mobile sensors, device orientation, accelerometer, gyroscope, touch, microphone, p5.sound, speech recognition, PhoneCamera, ML5 camera mapping, vibration, torch/flashlight, NFC, Bluetooth BLE, GPS/geolocation, geoDistance/geoInPolygon, lockGestures, enablePermissionsTap, enableHardwareTap, arbitrary hardware combinations, mobile browser permissions, p5.js 2 compatibility.
argument-hint	Describe the p5-phone example or API question

p5-phone: Mobile Hardware for p5.js

When to use this skill

Quick Start

For generated examples, produce a complete index.html and sketch.js unless the user asks for a single file or snippet.

HTML baseline (p5.js 2-compatible):

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Mobile p5.js App</title>
  <style>
    body { margin: 0; padding: 0; overflow: hidden; }
  </style>
  <script src="https://cdn.jsdelivr.net/npm/p5@2.2.3/lib/p5.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/p5.js-compatibility@0.2.0/src/preload.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/p5-phone@1.12.1/dist/p5-phone.min.js"></script>
</head>
<body>
  <script src="sketch.js"></script>
</body>
</html>

Add p5.sound only when the sketch uses microphone levels, oscillators, audio input, sound output, or speech. Place it after p5 and before p5-phone/sketch.js:

<script src="https://cdn.jsdelivr.net/npm/p5.sound@0.3.0/dist/p5.sound.min.js"></script>

Minimal sketch (sketch.js):

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  enableSensorTap('Tap to enable motion sensors');
}

function draw() {
  background(20);
  if (!window.sensorsEnabled) {
    fill(255);
    textAlign(CENTER, CENTER);
    text('Waiting for sensors', width / 2, height / 2);
    return;
  }
  // rotationX / rotationY / rotationZ are p5.js built-ins, live once sensorsEnabled is true.
  fill(0, 180, 255);
  circle(width / 2 + rotationY * 4, height / 2 + rotationX * 4, 80);
}

function mousePressed() {
  return false; // let p5-phone's gesture handling manage the touch
}

Golden Rules

Call lockGestures() in every mobile sketch setup(). It blocks pull-to-refresh, swipe-back, pinch-zoom, double-tap zoom, long-press menus, and overscroll so the canvas behaves like an app.
Request every permission from a user gesture. iOS grants sensitive APIs only during transient user activation (a tap/click). Never auto-request on page load — use an enable* activation UI.
Gate all hardware reads behind the matching window.*Enabled flag (sensorsEnabled, micEnabled, bleConnected, etc.). Reading before permission returns stale/undefined data.
Use mousePressed / mouseDragged / mouseReleased, not p5 1.x touchStarted / touchMoved / touchEnded. The mouse callbacks fire for both mouse and touch in p5.js 1.x and 2.x; the touch callbacks are removed/no-ops in p5.js 2.
Serve over HTTPS (or localhost). Sensors, mic, camera, NFC, BLE, GPS, and torch all require a secure context on mobile.
Need several hardware features from one tap? Use a single combined call — enablePermissionsTap(['sensors', 'torch']) — not several single-permission binds on the same gesture. One call keeps iOS transient activation intact and fires userSetupComplete() once.
Use exactly one activation style per permission need unless the user explicitly asks to compare styles.

Use p5.js built-ins — do not reimplement them

p5-phone concern	Use these p5.js built-ins (not custom code)	Notes
Device orientation	`rotationX`, `rotationY`, `rotationZ` (+ `pRotationX/Y/Z`)	p5 globals; p5-phone only gates them via `sensorsEnabled`
Acceleration	`accelerationX/Y/Z`, `pAccelerationX/Y/Z`	p5 globals
Rotation rate	`rotationRateAlpha`, `rotationRateBeta`, `rotationRateGamma`	p5 globals
Motion events / thresholds	`deviceMoved()`, `deviceShaken()`, `setMoveThreshold()`, `setShakeThreshold()`, `deviceOrientation`	define the callbacks as globals
Touch / pointer input	`mousePressed()`, `mouseDragged()`, `mouseReleased()`, `mouseX`, `mouseY`, `touches[]`	p5.js 2 unifies mouse+touch under the pointer model; use `touches[]` for multitouch. Do not add your own `addEventListener('touchstart', …)`
Drawing the camera feed	`image(cam, x, y, w, h)` + `cam.mapKeypoint()/mapBox()`	`PhoneCamera` integrates with p5's `image()`; map ML5 results with its helpers, not manual video compositing
Microphone level / analysis	`p5.AudioIn`, `p5.Amplitude`, `p5.FFT` (p5.sound)	not a raw Web Audio graph
Generated sound	`p5.Oscillator`, `p5.Envelope` (p5.sound)	prefer over `loadSound()` for portability
Loading images/audio/JSON/font	`await loadImage()/loadSound()/loadJSON()/loadFont()` in `async setup()`	p5.js 2: `load*` return Promises — no `preload()`. See the `p5js-2x` skill
Mapping / ranges	`map()`, `constrain()`, `lerp()`	p5 math helpers

Two specific traps worth calling out:

Motion values are p5.js built-ins, not p5-phone APIs. p5-phone only requests the permission and sets window.sensorsEnabled. The data (rotationX, accelerationX, deviceShaken(), …) comes straight from p5.js. Do not invent p5-phone getters for them.
There is no bleValue() getter. Read incoming BLE data from window.bleValues[name] or from the bleReceive(name, value) callback. bleValues is an object keyed by characteristic name.

Permissions model

Every hardware family exposes the same six activation styles. Pick one:

Tap — enable<Feature>Tap(message) — full-screen tap overlay with a frosted message box.
Button — enable<Feature>Button(buttonText, statusText?) — auto-generated button.
Canvas — enable<Feature>Canvas(message) — prompt drawn on the p5 canvas.
Banner — enable<Feature>Banner(message, position?) — animated slide-in banner (position = 'top'/'bottom').
Minimal — enable<Feature>Minimal(messageOrOpts?, opts?) — bare semi-transparent full-screen overlay with an optional radiating circular icon. Cleaner than Tap; adjustable { color, opacity, icon, iconColor, iconSize }.
On (custom element) — enable<Feature>On(selector) — bind activation to any existing HTML element by CSS selector.

Full matrix:

Feature	Tap	Button	Canvas	Banner	Minimal	On (selector)
Motion sensors	`enableSensorTap(msg)`	`enableSensorButton(text)`	`enableSensorCanvas(msg)`	`enableSensorBanner(msg)`	`enableSensorMinimal(msg\|opts)`	`enableSensorOn(sel)`
Microphone	`enableMicTap(msg)`	`enableMicButton(text)`	`enableMicCanvas(msg)`	`enableMicBanner(msg)`	`enableMicMinimal(msg\|opts)`	`enableMicOn(sel)`
Sound output	`enableSoundTap(msg)`	`enableSoundButton(text)`	`enableSoundCanvas(msg)`	`enableSoundBanner(msg)`	`enableSoundMinimal(msg\|opts)`	`enableSoundOn(sel)`
Speech	`enableSpeechTap(msg)`	`enableSpeechButton(text)`	`enableSpeechCanvas(msg)`	`enableSpeechBanner(msg)`	`enableSpeechMinimal(msg\|opts)`	`enableSpeechOn(sel)`
Vibration	`enableVibrationTap(msg)`	`enableVibrationButton(text)`	`enableVibrationCanvas(msg)`	`enableVibrationBanner(msg)`	`enableVibrationMinimal(msg\|opts)`	`enableVibrationOn(sel)`
Torch / flashlight	`enableTorchTap(msg)`	`enableTorchButton(text)`	`enableTorchCanvas(msg)`	`enableTorchBanner(msg)`	`enableTorchMinimal(msg\|opts)`	`enableTorchOn(sel)`
NFC	`enableNfcTap(msg)`	`enableNfcButton(text)`	`enableNfcCanvas(msg)`	`enableNfcBanner(msg)`	`enableNfcMinimal(msg\|opts)`	`enableNfcOn(sel)`
GPS / geolocation	`enableGeoTap(msg)`	`enableGeoButton(text)`	`enableGeoCanvas(msg)`	`enableGeoBanner(msg)`	`enableGeoMinimal(msg\|opts)`	`enableGeoOn(sel)`
Bluetooth (BLE)	`enableBleTap(opts?)`	`enableBleButton(opts?)`	`enableBleCanvas(opts?)`	`enableBleBanner(opts?)`	`enableBleMinimal(opts?)`	`enableBleOn(sel)`
Camera	`enableCameraTap(msg)`	`enableCameraButton(text)`	`enableCameraCanvas(msg)`	`enableCameraBanner(msg)`	`enableCameraMinimal(msg\|opts)`	`enableCameraOn(sel)`
Sensors + mic	`enableAllTap(msg)`	`enableAllButton(text)`	`enableAllCanvas(msg)`	`enableAllBanner(msg)`	`enableAllMinimal(msg\|opts)`	`enableAllOn(sel)`
Any combination	`enablePermissionsTap(list, msg)`	`enablePermissionsButton(list, text)`	`enablePermissionsCanvas(list, msg)`	`enablePermissionsBanner(list, msg)`	`enablePermissionsMinimal(list, msg\|opts)`	`enablePermissionsOn(sel, list)`

Notes:

enableBle* take an options object ({ label, message, statusText, position }), unlike the other families which take positional (message, position) / (buttonText, statusText).
enableGyro* is a legacy alias for enableSensor*. Prefer enableSensor* for new examples; use enableGyro* only to match older published sketches.
enableAll* is shorthand for sensors + mic. For any other mix, use enablePermissions*.
enableHardware* is an exact alias of enablePermissions*.
Minimal accepts the message as a string, as an options object, or both: enableSensorMinimal('Tap'), enableSensorMinimal({ opacity: 0.6, iconColor: '#fff' }), enableSensorMinimal('Tap', { color: '#000', icon: false }).

Activation style examples

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  enableSensorCanvas('Tap the canvas to begin'); // <-- the only line that changes
}

function draw() {
  background(20);
  if (!window.sensorsEnabled) return;            // gate all hardware reads

  fill(80, 200, 255);
  noStroke();
  circle(width / 2 + rotationY * 3, height / 2 + rotationX * 3, 60);

  fill(255);
  textAlign(CENTER, TOP);
  textSize(16);
  text('Tilt your phone to move the ball', width / 2, 30);
}

What each unlock screen looks like (replace the marked line above):

Tap — enableSensorTap('Tap to enable motion sensors') — full-screen dark overlay with a centered frosted-glass message box.
Button — enableSensorButton('ENABLE MOTION SENSORS') — a centered gradient button (plus optional status text) over the idle canvas.
Canvas — enableSensorCanvas('Tap the canvas to begin') — no overlay; a text hint is drawn on the canvas until the first touch.
Banner — enableSensorBanner('Tap to enable motion sensors', 'bottom') — a slim slide-in bar pinned to the top or bottom.
Minimal — enableSensorMinimal('Tap to begin') — a bare semi-transparent full-screen tint with a small radiating white icon. Adjustable: enableSensorMinimal({ color: '#0a0', opacity: 0.4, iconColor: '#fff' }).
On (custom element) — enableSensorOn('#start-btn') — no built-in UI; activation is bound to an HTML element you add yourself (e.g. <button id="start-btn">Start</button>).

Combining features

enablePermissions* (a.k.a. enableHardware*) takes a list plus a message. The list can be an array or a space/comma string.

Canonical tokens: sensors, mic, sound, speech, vibration, torch, nfc, geo, camera.

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  enablePermissionsTap(['sensors', 'mic'], 'Tap to enable motion + microphone');
}

function draw() {
  if (!window.sensorsEnabled || !window.micEnabled) return;
  // Use motion values and microphone input here.
}

Desktop QR and device detection (dev helpers)

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  showDesktopQr();                     // floating QR, desktop only; nothing on phone
  enableSensorMinimal('Tap to begin'); // minimal overlay on both
}

Status variables and callbacks

Read these window.* flags before using hardware data:

Motion: sensorsEnabled
Microphone: micEnabled
Sound: soundEnabled
Speech: speechEnabled
Vibration: vibrationEnabled
Torch: torchEnabled, torchSupported, torchActive, torchError, torchCapability
NFC: nfcEnabled, nfcStatus, nfcError, nfcTagAliases, lastNfcSerialNumber, lastNfcAlias, lastNfcMessage
GPS: geoEnabled, geoStatus, geoError, lastGeoPosition
BLE: bleSupported, bleConnected, bleStatus, bleError, bleDeviceName, bleValues
Camera: cameraEnabled
Gestures: gesturesLocked

Callbacks your sketch can define (p5-phone calls them if present):

userSetupComplete() — fires once immediately after permissions succeed.
deviceMoved(), deviceShaken() — p5.js motion events (available after sensorsEnabled).
nfcRead(message, serialNumber) — a tag was read.
geoRead(position) — a new GPS position arrived. position is a plain object: { latitude, longitude, accuracy, altitude, altitudeAccuracy, heading, speed, timestamp }.
onGeoError(error) — a GPS stream error after the watch started. error.code: 1=PERMISSION_DENIED, 2=POSITION_UNAVAILABLE, 3=TIMEOUT.
bleReceive(name, value) — a BLE characteristic notified or was read.

function userSetupComplete() {
  debug('Permissions ready');
}

Motion sensors

After window.sensorsEnabled is true, read p5.js built-ins:

Orientation: rotationX, rotationY, rotationZ
Acceleration: accelerationX, accelerationY, accelerationZ
Rotational velocity: rotationRateAlpha, rotationRateBeta, rotationRateGamma
Events: deviceMoved(), deviceShaken()
Thresholds: setMoveThreshold(value), setShakeThreshold(value)
Orientation state: deviceOrientation

iOS requires the sensor permission to be requested from a tap/click. Never auto-request motion permission on page load.

Microphone and sound

let mic;

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  mic = new p5.AudioIn();
  enableMicTap('Tap to enable microphone');
}

function draw() {
  background(0);
  if (!window.micEnabled) return;
  const level = mic.getLevel();
  circle(width / 2, height / 2, 40 + level * 600);
}

Speech recognition

Camera and ML5 (`PhoneCamera`)

createPhoneCamera(active = 'user', mirror = true, mode = 'fitHeight') returns a PhoneCamera. The camera is not initialized until an enableCamera* gesture (this fixes an iOS rotation bug).

active: 'user' (front) or 'environment' (rear).
mirror: mirror the display (front cameras usually true).
mode: 'fitHeight', 'fitWidth', 'cover', 'contain', or 'fixed'.

let cam;
let model;

function setup() {
  createCanvas(405, 720);
  lockGestures();
  cam = createPhoneCamera('user', true, 'fitHeight');
  enableCameraTap('Tap screen to enable camera');

  cam.onReady(async () => {
    model = await ml5.handPose({ maxHands: 1, runtime: 'mediapipe', flipped: false });
    model.detectStart(cam.videoElement, gotResults);
  });
}

PhoneCamera properties: ready, video (p5 element), videoElement (native <video> for ML5), width, height, active, mirror, mode, fixedWidth, fixedHeight.

Coordinate-mapping methods (video space → display space, mirror-aware):

cam.onReady(callback) — safe point to start ML5.
cam.getDimensions() → { x, y, width, height, scaleX, scaleY }.
cam.mapPoint(x, y) → { x, y }.
cam.mapKeypoint(keypoint) / cam.mapKeypoints(keypoints).
cam.mapBox(box) / cam.mapBoxes(boxes).
cam.remove() — stop and clean up the camera.

Set ML5 flipped: false when available — PhoneCamera already handles mirroring and coordinate mapping, so pass raw ML5 results through the map* helpers.

For ml5@1 with p5@2.2.3, add the preload-counter polyfill before loading ml5:

<script src="https://cdn.jsdelivr.net/npm/p5@2.2.3/lib/p5.js"></script>
<script src="https://cdn.jsdelivr.net/npm/p5.js-compatibility@0.2.0/src/preload.js"></script>
<script>
  p5.prototype._incrementPreload ||= function() {};
  p5.prototype._decrementPreload ||= function() {};
</script>
<script src="https://unpkg.com/ml5@1/dist/ml5.min.js"></script>

NFC

Android Chrome only, requires HTTPS. Compatible with widely available NFC Type 2 tags — NTAG213, NTAG215, NTAG216 — and any NDEF-formatted tag.

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  enableNfcTap('Tap to enable NFC');
}

function nfcRead(message, serialNumber) {
  setNfcTagAlias(serialNumber, 'example-tag');
  debug('Read NFC tag: ' + serialNumber);
}

function draw() {
  background(20);
  if (isNfcTag('example-tag')) {
    background(0, 120, 255);
  }
}

GPS / geolocation

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  // Optional: real GPS (~5-10m outdoors). Omit for coarse default.
  setGeoOptions({ enableHighAccuracy: true });
  enableGeoTap('Tap to enable GPS');
}

function draw() {
  background(20);
  const pos = window.lastGeoPosition;
  if (pos) {
    text(pos.latitude.toFixed(5) + ', ' + pos.longitude.toFixed(5), width / 2, height / 2);
  } else if (window.geoStatus === 'requesting-permission') {
    text('Acquiring GPS…', width / 2, height / 2);
  }
}

function geoRead(position) {
  // { latitude, longitude, accuracy, altitude, altitudeAccuracy, heading, speed, timestamp }
}

Bluetooth Low Energy (BLE)

Web Bluetooth exchanges typed values with Arduino-class peripherals. Call bleSetup() in setup() before any connect helper; connect from a user gesture via enableBle*.

Platform support:

Chrome/Edge on Android and desktop over HTTPS (or localhost).
iOS Safari/Chrome: not supported — use the Bluefy browser app.
Embedded iframes need allow="bluetooth".

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();

  bleSetup({
    namePrefix: 'p5phone',      // optional device-name filter
    autoReconnect: true,        // optional
    characteristics: [
      { name: 'temp', type: 'float', notify: true },
      { name: 'brightness', type: 'uint8', write: true }
    ]
  });

  enableBleButton({ label: 'Connect device' });
  showDebug();
}

function draw() {
  background(20);
  if (bleConnected) {
    text('temp: ' + (bleValues.temp ?? '—'), 20, 40);
  }
}

function mousePressed() {
  if (bleConnected) {
    bleWrite('brightness', floor(map(mouseX, 0, width, 0, 255)));
  }
  return false;
}

function bleReceive(name, value) {
  debug('BLE ' + name + ' = ' + value);
}

bleSetup(config) fields:

serviceUUID — hyphenated 128-bit UUID; defaults to the P5PhoneBLE service if omitted.
namePrefix — optional device-name filter.
autoReconnect — optional boolean.
characteristics — required array of { name, type, read?, write?, notify?, uuid? }. Each needs at least one of read/write/notify. Omit uuid to auto-derive it from the service UUID and declaration order (must match the P5PhoneBLE Arduino side). Names must be unique.

Valid type values: bool, int8, uint8, int16, uint16, int32, uint32, float, double, string, bytes. Numeric types use little-endian byte order.

Lifecycle and I/O:

enableBle*(options) — connect from a user gesture.
bleConnect() / bleDisconnect() — programmatic connect/disconnect (connect still needs a gesture).
bleRead(name) — async; reads and decodes a characteristic, updates window.bleValues[name], returns the value.
bleWrite(name, value, opts?) — async; opts.ack === false uses write-without-response (default is write-with-response). String writes over ~20 bytes may truncate on default-MTU peripherals.
isBleSupported() — boolean.
bleReceive(name, value) — your callback, fired on notify and on read.

Vibration

Use enableVibration* before vibrate(pattern). iOS does not support the Vibration API — write examples that still show useful feedback when window.vibrationEnabled is false.

function mousePressed() {
  if (window.vibrationEnabled) {
    vibrate([40, 30, 80]); // ms on / off / on, or a single number
  }
  return false;
}

stopVibration() cancels an ongoing pattern.

Torch / flashlight

Android-Chrome-oriented, requires HTTPS, works through a rear-camera stream. Enable with enableTorch*() (or enablePermissions*(['torch'])), then control the light:

torchOn(), torchOff(), toggleTorch(), setTorch(enabled) (async), stopTorch(), isTorchSupported().
Flashlight aliases: enableFlashlight*, flashlightOn(), flashlightOff(), toggleFlashlight(), setFlashlight(), stopFlashlight().

function setup() {
  createCanvas(windowWidth, windowHeight);
  lockGestures();
  enablePermissionsTap(['sensors', 'torch'], 'Tap to enable shake flashlight');
}

async function deviceShaken() {
  if (window.sensorsEnabled && window.torchEnabled) {
    await toggleTorch();
  }
}

Keep flashing pulses slow and short, avoid rapid strobing, and call torchOff() or stopTorch() when the effect ends.

lockGestures reference

lockGestures(options?)

options:

mode — 'fullscreen' (default) or 'embedded'.
element — target element for embedded mode (defaults to the first <canvas>).
warnBeforeLeave — show a leave-confirmation prompt (default false).
trapHistory — trap back/forward navigation (default true in fullscreen, false in embedded).

Debug console

For on-device troubleshooting, call showDebug() once in setup(), then log:

debug(message), debugWarn(message), debugError(message)
hideDebug(), toggleDebug()

Most useful for camera, NFC, BLE, and permission troubleshooting. Use sparingly in finished examples.

Platform support matrix

Feature	iOS Safari	Android Chrome
Motion sensors	✓ (permission tap required)	✓ (no prompt)
Microphone	✓	✓
Sound output	✓	✓
Speech recognition	Web Speech API support varies	✓
Camera	✓	✓
Vibration	✗ (API absent)	✓
Torch / flashlight	✗	✓
NFC	✗	✓ (HTTPS)
GPS / geolocation	✓ (HTTPS, user gesture)	✓ (HTTPS, user gesture)
Bluetooth BLE	✗ (use Bluefy app)	✓ (HTTPS)

All hardware requires a secure context (HTTPS or localhost).

Troubleshooting

Permission never fires / *Enabled stays false — the request must run inside a user gesture. Confirm you used an enable* activation UI and did not call it on load. On iOS a single gesture only grants one activation window, so combine features with one enablePermissions* call.
ML5 throws about _incrementPreload / preload with p5@2.2.3 — add the preload-counter polyfill shim before loading ml5 (see Camera section).
Torch or NFC does nothing — both are Android-Chrome + HTTPS only; check window.torchSupported / window.nfcStatus.
GPS hangs on "Acquiring…" or times out — cold start can take 5-30s, longer indoors; move outdoors, retry, and confirm OS-level Location Services is on. window.geoStatus tells you which state you're in.
GPS denied even after tapping Allow — the OS-level Location Services toggle (iOS Settings → Privacy & Security → Location Services; Android Settings → Location) must also be on; in-app browsers (Instagram/Facebook) usually fail — open in Safari/Chrome.
BLE won't connect on iPhone — Web Bluetooth is unavailable in iOS Safari/Chrome; use the Bluefy app.
Touch callbacks never run — touchStarted/Moved/Ended are no-ops in p5.js 2; switch to mousePressed/mouseDragged/mouseReleased.
Mic example throws in preview — don't call p5.Amplitude.setInput(mic) before window.micEnabled; read mic.getLevel() after permission.

Answering questions

Explain the browser-permission reason, especially iOS transient user activation.
Distinguish sensors, mic, sound-only, speech, camera, vibration, torch, NFC, and GPS permissions.
Mention HTTPS requirements for mobile hardware.
Mention p5.js 2 event changes when touch callbacks are involved.
Flag browser/device limits clearly: torch and NFC are Android-Chrome-oriented; vibration is unsupported on iOS; BLE needs Bluefy on iOS; speech recognition depends on Web Speech API support.
Point to the bundled examples under examples/ when useful — feature folders include movement/, microphone/, sound/, touch/, vibration/, camera/, torch/, nfc/, geo/, ble/, and combined/, plus ml5/, UIStyles/, and UXcompare/.
When migrating examples to the p5 Web Editor, follow the web-editor batch-sync workflow in docs/web-editor/ and record links in webeditorLinks.md.

Example quality checklist

Before finishing generated code, confirm:

lockGestures() is called in setup().
The permission request happens from a user-activation path (tap, button, banner, canvas, or custom element).
Hardware data is read only after the matching window.*Enabled flag is true.
The HTML includes the needed dependencies and no unused heavy libraries.
p5.js 2-compatible mouse* callbacks are used (not p5 1.x touch callbacks).
Text and canvas output fit mobile screens.
Asset-dependent examples either include the assets or clearly document that the user must upload them.
ML5 camera examples include the p5 2 compatibility shim and use PhoneCamera mapping helpers.

p5-phone

المزيد من هذا المستودع

المزيد من هذا المستودع

p5-phone: Mobile Hardware for p5.js

When to use this skill

Quick Start

Golden Rules

Use p5.js built-ins — do not reimplement them

Permissions model

Activation style examples

Combining features

Desktop QR and device detection (dev helpers)

Status variables and callbacks

Motion sensors

Microphone and sound

Speech recognition

Camera and ML5 (PhoneCamera)

NFC

GPS / geolocation

Bluetooth Low Energy (BLE)

Vibration

Torch / flashlight

lockGestures reference

Debug console

Platform support matrix

Troubleshooting

Answering questions

Example quality checklist

p5-phone: Mobile Hardware for p5.js

When to use this skill

Quick Start

Golden Rules

Use p5.js built-ins — do not reimplement them

Permissions model

Activation style examples

Combining features

Desktop QR and device detection (dev helpers)

Status variables and callbacks

Motion sensors

Microphone and sound

Speech recognition

Camera and ML5 (PhoneCamera)

NFC

GPS / geolocation

Bluetooth Low Energy (BLE)

Vibration

Torch / flashlight

lockGestures reference

Debug console

Platform support matrix

Troubleshooting

Answering questions

Example quality checklist

Camera and ML5 (`PhoneCamera`)

Camera and ML5 (`PhoneCamera`)