Docs

Run your React Native BLE app in the iOS Simulator or Android emulator against a real device somewhere else, a simulated device, or the real radio.

Quickstart

Install the package next to react-native-ble-plx and change one import:

npx expo install react-native-ble-plx
npm install react-native-ble-tunnel

// before: import {BleManager} from 'react-native-ble-plx'
import {BleManager} from 'react-native-ble-tunnel';

const manager = new BleManager({
  mode: __DEV__ ? 'remote' : 'native',
  remote: {session: {code: '482917', key: 'K7P2QX'}},
});

The code and key come from the support page: open it in Chrome next to the device, pick the device, done. Everything after the constructor is plain react-native-ble-plx.

Your own gateway

For a device that should stay reachable (lab, desk, test rack), run a gateway next to it. It connects outwards to DeviceSide, so it works behind NAT and needs no open ports.

Sign in and add a gateway. You get an id and a secret.
Start it on a Mac, Linux box or Raspberry Pi with Bluetooth (Node 22.18+):

git clone https://github.com/rt012/react-native-ble-tunnel
cd react-native-ble-tunnel/gateway && npm install
node src/main.ts --gw gw-xxxxxxxx --relay wss://deviceside.io --secret <secret>

Add --sim to try it with a simulated device. On Linux the gateway also runs in Docker (see gateway/README.md). No relay wanted? node src/main.ts --port 8787 and connect the app directly with remote: {url: 'ws://localhost:8787'}.

App keys

An app key lets your app, simulator or CI reach the gateways of your account. Create one in the dashboard:

new BleManager({mode: 'remote', remote: {gateway: {id: 'gw-xxxxxxxx', token: 'ebk_…'}}});

Keys work only for your own gateways and can be revoked any time. Keep them out of release builds: remote and sim throw in release builds unless you pass allowInRelease: true.

Modes

Mode	Talks to	Needs
`native`	the phone's Bluetooth through react-native-ble-plx itself	a device build
`remote`	a real device next to a gateway: support session (code + key), your gateway (id + app key) or a gateway URL in your network	a gateway
`sim`	a simulated device from a JSON scenario (services, values, notifications, disconnects)	nothing

Supported in remote and sim: scan, connect, discovery, read, write with and without response, monitor, cancelTransaction, MTU, disconnect events. Not yet: descriptors, bonding, background restore.

Free plan

2 gateways, 5 app keys, 20 sessions per day, 30 minutes per session. Support sessions through the support page are free. More: hello@deviceside.io.

Protocol

BLE over WebSocket: JSON frames, base64 payloads, one operation at a time per device. Clients send conn, gatt, read, write, sub; gateways answer and push ntf and dconn events. The full specification is in the repository.