chameleon-ultra.js

A JavaScript SDK for ChameleonUltra support Web Bluetooth API, Web Serial API and Node.js.

API Reference | Demos

TOC

• TOC
• Browser & OS compatibility
  • SerialPort (Node.js)
  • Web Bluetooth API
  • Web Serial API
  • Web Serial API Polyfill
• Installing
  • Package manager
  • CDN
• Getting Started
  • Slot Enable and Emulate Mifare 1K
  • Set new BLE Pairing Key and Enable BLE Pairing
• Related links

Browser & OS compatibility

SerialPort (Node.js)

Node SerialPort is a JavaScript library for connecting to serial ports that works in NodeJS and Electron.

Web Bluetooth API

A subset of the Web Bluetooth API is available in ChromeOS, Chrome for Android 6.0, Mac (Chrome 56) and Windows 10 (Chrome 70). See MDN's Browser compatibility table for more information.

For iPhone and iPad, the Web Bluetooth API is available in Bluefy – Web BLE Browser.

For Linux and earlier versions of Windows, enable the #experimental-web-platform-features flag in about://flags.

Web Serial API

The Web Serial API is available on all desktop platforms (ChromeOS, Linux, macOS, and Windows) in Chrome 89. See MDN's Browser compatibility table for more information.

Web Serial API Polyfill

On Android, support for USB-based serial ports is possible using the WebUSB API and the Serial API polyfill. This polyfill is limited to hardware and platforms where the device is accessible via the WebUSB API because it has not been claimed by a built-in device driver.

Installing

Package manager

Using npm:

$ npm install chameleon-ultra.js

# Also install SerialPort if you want to run in node.js
$ npm install serialport

Using yarn:

$ yarn add chameleon-ultra.js

# Also install SerialPort if you want to run in node.js
$ yarn add serialport

Once the package is installed, you can import the library using import or require:

// import
import { ChameleonUltra } from 'chameleon-ultra.js'
import WebbleAdapter from 'chameleon-ultra.js/plugin/WebbleAdapter'
import WebserialAdapter from 'chameleon-ultra.js/plugin/WebserialAdapter'
import SerialPortAdapter from 'chameleon-ultra.js/plugin/SerialPortAdapter'

// require
const { ChameleonUltra } = require('chameleon-ultra.js')
const WebbleAdapter = require('chameleon-ultra.js/plugin/WebbleAdapter')
const WebserialAdapter = require('chameleon-ultra.js/plugin/WebserialAdapter')
const SerialPortAdapter = require('chameleon-ultra.js/plugin/SerialPortAdapter')

CDN

Using jsDelivr CDN:

<!-- chameleon-ultra.js require lodash@4, place before any chameleon-ultra libraries -->
<script src="https://cdn.jsdelivr.net/npm/lodash@4/lodash.min.js"></script>

<!-- chameleon-ultra.js Core -->
<script src="https://cdn.jsdelivr.net/npm/chameleon-ultra.js@0/dist/iife/index.min.js"></script>
<!-- chameleon-ultra.js Crypto1 -->
<script src="https://cdn.jsdelivr.net/npm/chameleon-ultra.js@0/dist/iife/Crypto1.min.js"></script>
<!-- chameleon-ultra.js WebbleAdapter plugin -->
<script src="https://cdn.jsdelivr.net/npm/chameleon-ultra.js@0/dist/iife/plugin/WebbleAdapter.min.js"></script>
<!-- chameleon-ultra.js WebserialAdapter plugin -->
<script src="https://cdn.jsdelivr.net/npm/chameleon-ultra.js@0/dist/iife/plugin/WebserialAdapter.min.js"></script>

After the script tag, you can use the chameleon-ultra.js as following:

const { Buffer, ChameleonUltra, WebbleAdapter, WebserialAdapter } = window.ChameleonUltraJS

const ultraUsb = new ChameleonUltra()
ultraUsb.use(new WebserialAdapter())
const ultraBle = new ChameleonUltra()
ultraBle.use(new WebbleAdapter())

Getting Started

Slot Enable and Emulate Mifare 1K

async function run (ultra) {
  const { Buffer, DeviceMode, FreqType, Slot, TagType } = window.ChameleonUltraJS
  // set slot tag type and reset data
  await ultra.cmdSlotChangeTagType(Slot.SLOT_8, TagType.MIFARE_1024)
  await ultra.cmdSlotResetTagType(Slot.SLOT_8, TagType.MIFARE_1024)
  // enable slot
  await ultra.cmdSlotSetEnable(Slot.SLOT_8, FreqType.HF, true)
  // set active slot
  await ultra.cmdSlotSetActive(Slot.SLOT_8)
  // set anti-collision and write emu block
  await ultra.cmdHf14aSetAntiCollData({
    uid: Buffer.from('11223344', 'hex'), 
    atqa: Buffer.from('0400', 'hex'), 
    sak: Buffer.from('08', 'hex'),
  })
  await ultra.cmdMf1EmuWriteBlock(0, Buffer.from('11223344440804000000000000000000', 'hex'))
  // save slot settings
  await ultra.cmdSlotSaveSettings()
  // set device mode
  await ultra.cmdChangeDeviceMode(DeviceMode.TAG)
}

// you can run in DevTools of https://taichunmin.idv.tw/chameleon-ultra.js/test.html
await run(vm.ultra)

// or run with new ChaneleonUltra instance
const { ChameleonUltra, WebserialAdapter } = window.ChameleonUltraJS
const ultraUsb = new ChameleonUltra()
ultraUsb.use(new WebserialAdapter())
await run(ultraUsb)

Set new BLE Pairing Key and Enable BLE Pairing

async function run (ultra) {
  await ultra.cmdBleSetPairingKey('654321')
  await ultra.cmdBleDeleteAllBonds() // need to delete all bonds before change pairing mode
  await ultra.cmdBleSetPairingMode(true)
}

// you can run in DevTools of https://taichunmin.idv.tw/chameleon-ultra.js/test.html
await run(vm.ultra)

// or run with new ChaneleonUltra instance
const { ChameleonUltra, WebserialAdapter } = window.ChameleonUltraJS
const ultraUsb = new ChameleonUltra()
ultraUsb.use(new WebserialAdapter())
await run(ultraUsb)

Related links

• GitHub RfidResearchGroup/ChameleonUltra
• Chameleon Ultra Guide
• Chameleon Ultra GUI Documentation