Api js/rfid

[Senape3000]

Proposed Changes

This PR adds RFID JavaScript API bindings to the Bruce firmware JS interpreter, enabling scripts to interact with RFID readers (PN532, RC522/RFID2) programmatically without launching the Tag-O-Matic UI.

Key additions:

• New require("rfid") module with read() and readUID() functions
• Headless TagOMatic mode for non-interactive RFID operations
• Full support for existing RFID hardware (PN532 I2C/SPI, RC522/RFID2)
• Configurable timeout for tag detection
• Complete tag data access (UID, type, SAK, ATQA, memory dump, page count)

This feature enables use cases like automated tag scanning, inventory management, access control systems, and custom RFID workflows directly from JavaScript.

Types of Changes

• ✨ New Feature: RFID JavaScript API integration
• 🔧 Enhancement: Headless mode for TagOMatic
• 📚 Documentation: Added RFID_API_README.md with usage examples

Verification

Manual Testing:

1. Load a script using const rfid = require("rfid");
2. Call rfid.readUID(10) - verify UID string returned on tag detection
3. Call rfid.read(10) - verify complete object with all tag fields returned
4. Test timeout behavior (no tag present) - verify null / empty string returned
5. Verify Tag-O-Matic UI still works normally (backward compatibility)

Hardware Tested:

• ✅ PN532 (I2C mode)

Tag Types Tested:

• ✅ MIFARE Classic 1K
• ✅ MIFARE Ultralight
• ✅ NTAG213/215/216

Example Scripts:
Two working example scripts included in testing:

• TAG READ FUNCTION
• UID READ FUNCTION

Testing

Manual Testing Performed:

• ✅ Both read() and readUID() functions tested with real hardware
• ✅ Timeout handling verified
• ✅ UI-based script (Rfid_READ_UID.js) tested successfully
• ✅ Backward compatibility: Tag-O-Matic UI unchanged and functional
• ✅ Memory management: TagOMatic headless constructor/destructor verified

Unit Tests:
Not applicable - this PR adds JS bindings for hardware interaction. Manual hardware testing required.

Linked Issues

N/A - New feature implementation

User-Facing Change

New RFID JavaScript API: Scripts can now read RFID tags using `require("rfid")`. 
Adds `rfid.read(timeout)` for complete tag info and `rfid.readUID(timeout)` for fast UID-only reading.
Supports PN532 and RC522/RFID2 modules. See `RFID_API_README.md` for documentation and examples.
Further Comments
Implementation Details:

Minimal invasive changes to existing codebase

Reuses existing RFIDInterface and RFID driver implementations

New headless constructor prevents UI interference

JS bindings follow existing pattern used by IR, GPIO, and other modules

Files Modified: 4
Files Added: 2
Total LOC Changed: ~120 lines

Documentation:
Comprehensive RFID_API_README.md included with:

API reference with TypeScript signatures

Multiple usage examples (console, UI-based, multi-tag)

Implementation details

Compatibility matrix

Backward Compatibility:
✅ No breaking changes - existing Tag-O-Matic functionality completely preserved

Future Enhancements (out of scope for this PR):

rfid.write() for writing data to tags

rfid.clone() for UID cloning

rfid.erase() for tag erasure

rfid.save() / rfid.load() for file operations

These can be added incrementally as the API foundation is now in place.

[Senape3000]

Added new functions and little bugfix for "dialog_js" and "PN532" and "RFID2"

----> UPDATED DOCS <----

Scripts for testing RFID API -already tested-

Need some time to implement SRIX TOOL

[Senape3000]

Added function to add a mifare key from API (validation system already implemented in Refactoring/mifare keys handling #1990)

----> UPDATED DOCS <----

Scripts for testing RFID API -already tested-

Need some time to implement SRIX TOOL

[bmorcelli]

moved this PR to dev, after rebase dev to main (with your SRIX tool implementation), where we are currently working..

Should we wait for SRIX on interpreter in this PR?

[Senape3000]

ok, I'll put it back in draft, let's wait for SRIX to be implemented in the api too.
Thanks for moving to dev

[Senape3000]

This PR includes a full review and update of the PN532 handling to ensure compatibility with the I2C polling mode, so SRIX operations work reliably across more boards/configurations. While this approach makes write operations noticeably slower, it provides a working baseline “everywhere” for now (polling is less efficient than using IRQ/RST lines).

In the future, once a T-Embed is available for testing, the plan is to validate and improve the faster path for devices that expose IRQ and RST pins (hardware-assisted mode), so performance can be significantly improved where supported.

The PR also contains small library improvements and a complete set of additions/updates to RFID_JS (including SRIX bindings), bringing the JS API to a fully usable state for reading, writing, saving/loading, and block-level operations.

All changes are ready for merge: the implementation has been tested thoroughly and successfully end-to-end.

As usual:

----> SRIX API DOCS <----