npm - p5-phone - Versions diffs - 1.8.0 → 1.9.0 - Mend

p5-phone 1.8.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (53) hide show

package/README.md CHANGED Viewed

@@ -58,6 +58,7 @@ p5-phone supports both **p5.js 1.x** and **p5.js 2.0+**.
 | Microphone / Speech / Sound | ✅ | ✅ |
 | Camera (PhoneCamera) | ✅ | ✅ |
 | Vibration | ✅ | ✅ |
+| NFC Tag Reading (Android only) | ✅ | ✅ |
 | Debug console | ✅ | ✅ |
 | lockGestures() | ✅ | ✅ |
 | `touchStarted()` / `touchEnded()` | ✅ | ❌ Use `mousePressed()` / `mouseReleased()` |
@@ -86,6 +87,7 @@ p5-phone automatically detects the p5.js version and adjusts its internal touch
   - [Speech Recognition Activation](#speech-recognition-activation)
   - [Combined Activation](#combined-activation)
   - [Vibration Motor (Android Only)](#vibration-motor-android-only)
+  - [NFC Tag Reading (Android Only)](#nfc-tag-reading-android-only)
   - [PhoneCamera (ML5 Integration)](#phonecamera-ml5-integration)
   - [Debug System](#debug-system)
 - [Permission UI Styles](#permission-ui-styles)
@@ -100,10 +102,10 @@ p5-phone automatically detects the p5.js version and adjusts its internal touch
 ```html
 <!-- Minified version (recommended) -->
-<script src="https://cdn.jsdelivr.net/npm/p5-phone@1.8.0/dist/p5-phone.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/p5-phone@1.9.0/dist/p5-phone.min.js"></script>
 <!-- Development version (larger, with comments) -->
-<!-- <script src="https://cdn.jsdelivr.net/npm/p5-phone@1.8.0/dist/p5-phone.js"></script> -->
+<!-- <script src="https://cdn.jsdelivr.net/npm/p5-phone@1.9.0/dist/p5-phone.js"></script> -->
 ```
 ### Basic Setup
@@ -132,7 +134,7 @@ p5-phone automatically detects the p5.js version and adjusts its internal touch
   <!-- For p5.js 2.0: <script src="https://cdn.jsdelivr.net/npm/p5@2/lib/p5.min.js"></script> -->
   <!-- Load p5-phone library -->
-  <script src="https://cdn.jsdelivr.net/npm/p5-phone@1.8.0/dist/p5-phone.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/p5-phone@1.9.0/dist/p5-phone.min.js"></script>
 </head>
 <body>
@@ -302,6 +304,7 @@ this.enableGyroTap('Tap to start');
 - `window.soundEnabled` - Boolean indicating if sound output is active
 - `window.speechEnabled` - Boolean indicating if speech recognition is active
 - `window.vibrationEnabled` - Boolean indicating if vibration is available (Android only)
+- `window.nfcEnabled` - Boolean indicating if NFC scanning is active (Android only)
 **Usage:**
 ```javascript
@@ -326,6 +329,11 @@ function draw() {
     // Safe to use vibration (Android only)
     vibrate(50);
   }
+  if (window.nfcEnabled) {
+    // NFC scanning is active (Android only)
+    // Tag data arrives via nfcRead() callback
+  }
 }
 // You can also use them for conditional UI
@@ -638,6 +646,94 @@ function gameOver() {
 - Don't overuse - vibration can quickly drain battery
 - Test on Android devices as iOS doesn't support vibration
+### NFC Tag Reading (Android Only)
+**Purpose:** Read NFC (Near Field Communication) tags using the Web NFC API. Ideal for interactive installations, scavenger hunts, or any sketch that responds to physical NFC tags.
+**⚠️ Platform Support:**
+- ✅ **Android** - Chrome 89+ and Samsung Internet 15+
+- ❌ **iOS** - Not supported (Web NFC API not available on iOS)
+- Requires **HTTPS** — NFC is blocked on insecure origins
+**Important:** The Web NFC API requires user activation (a tap or click) before scanning can begin — the same pattern used by all other p5-phone permission functions. On unsupported devices/browsers, `window.nfcEnabled` will be `false` and calls will be safely ignored with console warnings.
+**Commands:**
+- `enableNfcTap(message)` - Tap anywhere on screen to enable NFC scanning
+- `enableNfcButton(text)` - Creates a button with custom text to enable NFC
+- `stopNfc()` - Stop NFC scanning
+**Status Variables:**
+- `window.nfcEnabled` - Boolean indicating if NFC scanning is active
+- `window.lastNfcMessage` - Object containing the most recently read tag's data
+- `window.lastNfcSerialNumber` - Serial number string of the most recently read tag
+**User Callback:**
+Define an `nfcRead()` function in your sketch to receive tag data when a tag is scanned:
+```javascript
+function nfcRead(message, serialNumber) {
+  // message.serialNumber — tag serial number
+  // message.records — array of NDEF records, each with:
+  //   .recordType — 'text', 'url', 'mime', etc.
+  //   .data — decoded content (string for text/url, object for JSON, raw for others)
+  //   .mediaType — MIME type (for 'mime' records)
+  //   .id — record id (if present)
+  //   .raw — original DataView
+}
+```
+**Usage:**
+```javascript
+let tagText = 'No tag scanned yet';
+function setup() {
+  createCanvas(windowWidth, windowHeight);
+  lockGestures();
+  enableNfcTap('Tap to enable NFC');
+}
+function draw() {
+  background(220);
+  textAlign(CENTER, CENTER);
+  textSize(20);
+  if (!window.nfcEnabled) {
+    text('NFC not active', width / 2, height / 2);
+  } else {
+    text(tagText, width / 2, height / 2);
+    text('Hold an NFC tag near your phone', width / 2, height / 2 + 40);
+  }
+}
+function nfcRead(message, serialNumber) {
+  tagText = 'Tag: ' + serialNumber;
+  for (let record of message.records) {
+    if (record.recordType === 'text' || record.recordType === 'url') {
+      tagText += '\n' + record.data;
+    }
+  }
+}
+```
+**Record Types:**
+NFC tags contain NDEF records. The most common types are:
+| Record Type | `record.data` Contains | Example |
+|-------------|----------------------|----------|
+| `text` | Decoded string | `"Hello World"` |
+| `url` | Decoded URL string | `"https://example.com"` |
+| `mime` | Decoded string or parsed JSON | `{ id: 42 }` |
+| other | Raw `DataView` | Binary data |
+**Best Practices:**
+- Always check `window.nfcEnabled` before relying on NFC features
+- Use the `nfcRead()` callback for real-time tag processing
+- Use `window.lastNfcMessage` in `draw()` for displaying the most recent tag
+- Test on Android devices with Chrome — NFC is not available on iOS or desktop browsers
+- Tags must be NDEF-formatted to be read by the Web NFC API
 ### Speech Recognition Activation
 **Purpose:** Enable the Web Speech API for voice input and speech-to-text in mobile browsers.
@@ -924,6 +1020,7 @@ The canvas displays a centered message until the user taps. Great for "full-scre
 - `enableSensorCanvas(message)`
 - `enableMicCanvas(message)`
 - `enableSpeechCanvas(message)`
+- `enableNfcCanvas(message)`
 - `enableAllCanvas(message)`
 - `enableCameraCanvas(message)`
@@ -950,6 +1047,7 @@ A styled banner slides in from the top of the screen with an animated entrance.
 - `enableSensorBanner(message)`
 - `enableMicBanner(message)`
 - `enableSpeechBanner(message)`
+- `enableNfcBanner(message)`
 - `enableAllBanner(message)`
 - `enableCameraBanner(message)`
@@ -977,6 +1075,7 @@ Bind the permission activation to any existing HTML element on the page using a
 - `enableSensorOn(selector)`
 - `enableMicOn(selector)`
 - `enableSpeechOn(selector)`
+- `enableNfcOn(selector)`
 - `enableAllOn(selector)`
 - `enableCameraOn(selector)`

package/dist/p5-phone.js CHANGED Viewed

@@ -87,9 +87,14 @@ window.soundEnabled = false;
 window.gesturesLocked = false;
 window.vibrationEnabled = false;
 window.speechEnabled = false;
+window.nfcEnabled = false;
+window.lastNfcMessage = null;
+window.lastNfcSerialNumber = null;
 // Internal state
 let _micInstance = null;
+let _nfcReader = null;
+let _nfcAbortController = null;
 // p5.js version detection (1.x vs 2.x)
 const _p5MajorVersion = (typeof p5 !== 'undefined' && p5.VERSION)
@@ -235,6 +240,30 @@ function enableVibrationTap(message = 'Tap screen to enable vibration') {
   });
 }
+/**
+ * Enable NFC tag reading with a button interface
+ * Creates a start button that user must click
+ * Note: Web NFC is supported on Android Chrome 89+ only, not iOS
+ */
+function enableNfcButton(buttonText = 'ENABLE NFC', statusText = 'Enabling NFC...') {
+  _createPermissionButton(buttonText, statusText, async () => {
+    await _requestNfcPermission();
+    console.log('✅ NFC enabled via button');
+  });
+}
+/**
+ * Enable NFC tag reading with tap-to-start
+ * User taps anywhere on screen to enable
+ * Note: Web NFC is supported on Android Chrome 89+ only, not iOS
+ */
+function enableNfcTap(message = 'Tap screen to enable NFC') {
+  _createTapToEnable(message, async () => {
+    await _requestNfcPermission();
+    console.log('✅ NFC enabled via tap');
+  });
+}
 /**
  * Enable both motion sensors and microphone with a button interface
  * Creates a start button that user must click to enable both
@@ -318,6 +347,16 @@ function enableVibrationCanvas(message = 'Touch to start') {
   });
 }
+/**
+ * Enable NFC on first canvas touch
+ */
+function enableNfcCanvas(message = 'Touch to start') {
+  _createCanvasToEnable(message, async () => {
+    await _requestNfcPermission();
+    console.log('✅ NFC enabled via canvas touch');
+  });
+}
 /**
  * Enable both motion sensors and microphone on first canvas touch
  */
@@ -385,6 +424,13 @@ function enableVibrationBanner(message = 'Tap to enable vibration', position = '
   });
 }
+function enableNfcBanner(message = 'Tap to enable NFC', position = 'top') {
+  _createBannerToEnable(message, position, async () => {
+    await _requestNfcPermission();
+    console.log('✅ NFC enabled via banner');
+  });
+}
 function enableAllBanner(message = 'Tap to enable sensors & microphone', position = 'top') {
   _createBannerToEnable(message, position, async () => {
     await _requestMotionPermissionsCore();
@@ -445,6 +491,13 @@ function enableVibrationOn(selector) {
   });
 }
+function enableNfcOn(selector) {
+  _bindPermissionTo(selector, async () => {
+    await _requestNfcPermission();
+    console.log('✅ NFC enabled via custom element');
+  });
+}
 function enableAllOn(selector) {
   _bindPermissionTo(selector, async () => {
     await _requestMotionPermissionsCore();
@@ -494,6 +547,19 @@ function stopVibration() {
   }
 }
+/**
+ * Stop NFC scanning
+ */
+function stopNfc() {
+  if (_nfcAbortController) {
+    _nfcAbortController.abort();
+    _nfcAbortController = null;
+  }
+  _nfcReader = null;
+  window.nfcEnabled = false;
+  console.log('NFC scanning stopped');
+}
 // =========================================
 // INTERNAL PERMISSION HANDLERS
 // =========================================
@@ -619,6 +685,102 @@ async function _requestVibrationPermissionCore() {
   }
 }
+async function _requestNfcPermissionCore() {
+  try {
+    // Check if Web NFC API is supported
+    if (!('NDEFReader' in window)) {
+      console.warn('⚠️ Web NFC API not supported on this device/browser (Android Chrome 89+ required)');
+      if (_debugVisible) {
+        debugWarn('Web NFC not supported on this device/browser');
+      }
+      window.nfcEnabled = false;
+      return;
+    }
+    _nfcAbortController = new AbortController();
+    _nfcReader = new NDEFReader();
+    _nfcReader.onreading = (event) => {
+      const serialNumber = event.serialNumber || '';
+      const decoder = new TextDecoder();
+      const records = [];
+      for (const record of event.message.records) {
+        const entry = {
+          recordType: record.recordType,
+          mediaType: record.mediaType || null,
+          id: record.id || null,
+          data: null,
+          raw: record.data
+        };
+        if (record.recordType === 'text' || record.recordType === 'url') {
+          entry.data = decoder.decode(record.data);
+        } else if (record.recordType === 'mime' && record.mediaType) {
+          try {
+            const text = decoder.decode(record.data);
+            if (record.mediaType.includes('json')) {
+              entry.data = JSON.parse(text);
+            } else {
+              entry.data = text;
+            }
+          } catch (e) {
+            entry.data = record.data;
+          }
+        } else {
+          entry.data = record.data;
+        }
+        records.push(entry);
+      }
+      const message = { serialNumber: serialNumber, records: records };
+      window.lastNfcMessage = message;
+      window.lastNfcSerialNumber = serialNumber;
+      // Call user-defined callback if it exists
+      if (typeof nfcRead === 'function') {
+        nfcRead(message, serialNumber);
+      }
+      console.log('NFC tag read — serial:', serialNumber, 'records:', records.length);
+      if (_debugVisible) {
+        debug('NFC tag read: ' + serialNumber);
+      }
+    };
+    _nfcReader.onreadingerror = (event) => {
+      console.warn('⚠️ NFC read error — tag may be incompatible or out of range');
+      if (_debugVisible) {
+        debugWarn('NFC read error — tag incompatible or out of range');
+      }
+    };
+    await _nfcReader.scan({ signal: _nfcAbortController.signal });
+    window.nfcEnabled = true;
+    console.log('✅ NFC scanning active');
+  } catch (error) {
+    if (error.name === 'NotAllowedError') {
+      console.warn('⚠️ NFC permission denied by user');
+      if (_debugVisible) {
+        debugWarn('NFC permission denied');
+      }
+    } else if (error.name === 'NotSupportedError') {
+      console.warn('⚠️ NFC not supported on this device');
+      if (_debugVisible) {
+        debugWarn('NFC not supported on this device');
+      }
+    } else {
+      console.error('NFC permission error:', error);
+      if (_debugVisible) {
+        debugError('NFC error: ' + error.message);
+      }
+    }
+    window.nfcEnabled = false;
+  }
+}
 // Wrapped versions that notify the sketch (used by single-permission functions)
 async function _requestMotionPermissions() {
   await _requestMotionPermissionsCore();
@@ -645,6 +807,11 @@ async function _requestVibrationPermission() {
   _notifySketchReady();
 }
+async function _requestNfcPermission() {
+  await _requestNfcPermissionCore();
+  _notifySketchReady();
+}
 function _notifySketchReady() {
   // Call userSetupComplete if it exists
   if (typeof userSetupComplete === 'function') {
@@ -659,6 +826,7 @@ function _notifySketchReady() {
       sound: window.soundEnabled,
       speech: window.speechEnabled,
       vibration: window.vibrationEnabled,
+      nfc: window.nfcEnabled,
       gestures: window.gesturesLocked
     }
   }));
@@ -1403,6 +1571,9 @@ window.enableVibrationTap = enableVibrationTap;
 window.enableVibrationButton = enableVibrationButton;
 window.vibrate = vibrate;
 window.stopVibration = stopVibration;
+window.enableNfcTap = enableNfcTap;
+window.enableNfcButton = enableNfcButton;
+window.stopNfc = stopNfc;
 window.enableAllTap = enableAllTap;
 window.enableAllButton = enableAllButton;
@@ -1412,6 +1583,7 @@ window.enableMicCanvas = enableMicCanvas;
 window.enableSoundCanvas = enableSoundCanvas;
 window.enableSpeechCanvas = enableSpeechCanvas;
 window.enableVibrationCanvas = enableVibrationCanvas;
+window.enableNfcCanvas = enableNfcCanvas;
 window.enableAllCanvas = enableAllCanvas;
 window.enableCameraCanvas = enableCameraCanvas;
@@ -1421,6 +1593,7 @@ window.enableMicBanner = enableMicBanner;
 window.enableSoundBanner = enableSoundBanner;
 window.enableSpeechBanner = enableSpeechBanner;
 window.enableVibrationBanner = enableVibrationBanner;
+window.enableNfcBanner = enableNfcBanner;
 window.enableAllBanner = enableAllBanner;
 window.enableCameraBanner = enableCameraBanner;
@@ -1430,6 +1603,7 @@ window.enableMicOn = enableMicOn;
 window.enableSoundOn = enableSoundOn;
 window.enableSpeechOn = enableSpeechOn;
 window.enableVibrationOn = enableVibrationOn;
+window.enableNfcOn = enableNfcOn;
 window.enableAllOn = enableAllOn;
 window.enableCameraOn = enableCameraOn;
@@ -2185,6 +2359,9 @@ if (typeof p5 !== 'undefined' && p5.prototype) {
   p5.prototype.enableVibrationButton = enableVibrationButton;
   p5.prototype.vibrate = vibrate;
   p5.prototype.stopVibration = stopVibration;
+  p5.prototype.enableNfcTap = enableNfcTap;
+  p5.prototype.enableNfcButton = enableNfcButton;
+  p5.prototype.stopNfc = stopNfc;
   p5.prototype.enableAllTap = enableAllTap;
   p5.prototype.enableAllButton = enableAllButton;
@@ -2194,6 +2371,7 @@ if (typeof p5 !== 'undefined' && p5.prototype) {
   p5.prototype.enableSoundCanvas = enableSoundCanvas;
   p5.prototype.enableSpeechCanvas = enableSpeechCanvas;
   p5.prototype.enableVibrationCanvas = enableVibrationCanvas;
+  p5.prototype.enableNfcCanvas = enableNfcCanvas;
   p5.prototype.enableAllCanvas = enableAllCanvas;
   p5.prototype.enableCameraCanvas = enableCameraCanvas;
@@ -2203,6 +2381,7 @@ if (typeof p5 !== 'undefined' && p5.prototype) {
   p5.prototype.enableSoundBanner = enableSoundBanner;
   p5.prototype.enableSpeechBanner = enableSpeechBanner;
   p5.prototype.enableVibrationBanner = enableVibrationBanner;
+  p5.prototype.enableNfcBanner = enableNfcBanner;
   p5.prototype.enableAllBanner = enableAllBanner;
   p5.prototype.enableCameraBanner = enableCameraBanner;
@@ -2212,6 +2391,7 @@ if (typeof p5 !== 'undefined' && p5.prototype) {
   p5.prototype.enableSoundOn = enableSoundOn;
   p5.prototype.enableSpeechOn = enableSpeechOn;
   p5.prototype.enableVibrationOn = enableVibrationOn;
+  p5.prototype.enableNfcOn = enableNfcOn;
   p5.prototype.enableAllOn = enableAllOn;
   p5.prototype.enableCameraOn = enableCameraOn;
@@ -2257,6 +2437,9 @@ if (typeof p5 !== 'undefined' && typeof p5.registerAddon === 'function') {
     fn.enableVibrationButton = enableVibrationButton;
     fn.vibrate = vibrate;
     fn.stopVibration = stopVibration;
+    fn.enableNfcTap = enableNfcTap;
+    fn.enableNfcButton = enableNfcButton;
+    fn.stopNfc = stopNfc;
     fn.enableAllTap = enableAllTap;
     fn.enableAllButton = enableAllButton;
@@ -2266,6 +2449,7 @@ if (typeof p5 !== 'undefined' && typeof p5.registerAddon === 'function') {
     fn.enableSoundCanvas = enableSoundCanvas;
     fn.enableSpeechCanvas = enableSpeechCanvas;
     fn.enableVibrationCanvas = enableVibrationCanvas;
+    fn.enableNfcCanvas = enableNfcCanvas;
     fn.enableAllCanvas = enableAllCanvas;
     fn.enableCameraCanvas = enableCameraCanvas;
@@ -2275,6 +2459,7 @@ if (typeof p5 !== 'undefined' && typeof p5.registerAddon === 'function') {
     fn.enableSoundBanner = enableSoundBanner;
     fn.enableSpeechBanner = enableSpeechBanner;
     fn.enableVibrationBanner = enableVibrationBanner;
+    fn.enableNfcBanner = enableNfcBanner;
     fn.enableAllBanner = enableAllBanner;
     fn.enableCameraBanner = enableCameraBanner;
@@ -2284,6 +2469,7 @@ if (typeof p5 !== 'undefined' && typeof p5.registerAddon === 'function') {
     fn.enableSoundOn = enableSoundOn;
     fn.enableSpeechOn = enableSpeechOn;
     fn.enableVibrationOn = enableVibrationOn;
+    fn.enableNfcOn = enableNfcOn;
     fn.enableAllOn = enableAllOn;
     fn.enableCameraOn = enableCameraOn;