BLE API Reference
This reference describes the BLE API implemented by WisNode Tag running TrackIT firmware. It is intended for developers who need to build a custom mobile app, factory provisioning tool, or service tool to configure and maintain the device locally over BLE.
Use this API when the official TrackIT app does not fully match your integration workflow, such as provisioning WisNode Tag for a third-party LoRaWAN® Network Server, reading DevEUI/AppEUI/AppKey and region information, binding APPID/DEVID, setting work mode or reporting interval, checking device status, or preparing the device for Nordic DFU.
Use the official TrackIT app for device configuration. For LoRaWAN uplink payload format and decoding information, see the LoRaWAN Payload Reference.
API Coverage
This document covers the BLE interfaces that are intended for customer or developer integration.
Supported API Features
| Feature | Guidance |
|---|---|
| BLE discovery and connection | Scan for WisNode Tag, identify the BLE device name, and establish a BLE connection. |
| GATT service discovery | Discover the BLE services and characteristics exposed by the device. |
| Device and LoRaWAN information | Read device information, battery status, diagnostic data, and LoRaWAN configuration such as DevEUI, AppEUI, AppKey, region, work mode, APPID, and DEVID. |
| Command control | Send supported control commands through Custom TX CMD. |
| Command response | Receive and handle command responses through Custom RX Notify. |
Unsupported API Features
| Feature | Guidance |
|---|---|
| EPO transfer over BLE | EPO transfer is not enabled for customer BLE integration. Do not implement or rely on EPO transfer over BLE. |
| Custom FOTA packet protocol | Do not use the custom FFA0 / FFA1 FOTA packet protocol for firmware updates. WisNode Tag firmware updates must be performed through Nordic DFU. |
Recommended Integration Flow
A custom app or tool should follow the integration flow below when communicating with WisNode Tag over BLE.
- Scan for a BLE device name in the format
RAK_XXXX. - Connect to the device.
- Run GATT service and characteristic discovery.
- Enable notifications on Custom RX Notify (
0039f9f7-e86c-4a2f-b612-650358c82d07) before sending commands. - Optionally enable indications on Battery Level to receive live battery updates.
- Read Wireless Info characteristics to obtain MAC, SN, DevEUI, AppEUI, AppKey, work mode, interval, and region.
- Send supported control commands through Custom TX CMD.
- Treat
0xAFresponses as command-handler acceptance, not guaranteed final success. - For asynchronous operations, such as LoRaWAN region switching, wait briefly and re-read the related characteristic, such as Region Info, to confirm the final applied value.
Integration Flow Details
This section describes the BLE parameters, GATT services, characteristics, and command formats used in each step of the recommended integration flow.
Step 1: Scan and Identify the Device
WisNode Tag advertises as a connectable and scannable BLE peripheral. A custom app or provisioning tool can identify the device by its BLE advertising name and scan response data.
BLE Advertising Parameters
| Field | Value |
|---|---|
| Advertising interval | 40 ms |
| Single advertising timeout | 30 s |
| Device name format | RAK_XXXX |
XXXX is derived from the last 2 bytes of the LoRaWAN DevEUI.
Advertising Data
| Field | Value |
|---|---|
| Flags | 0x06 |
| Complete Name | RAK_XXXX |
| Manufacturer Data | ASCII RADACAT + 00 00 14 00 |
| Complete 16-bit UUID | 0x1800 |
Scan Response
The scan response includes the serial number as manufacturer data.
If the serial number cannot be read from NVM, the firmware uses the following fallback value:
9101003L0251100000
Step 2: Connect to the Device
After the target WisNode Tag is identified, establish a BLE connection with the device.
Connection Parameters
These values describe the BLE connection behavior used by WisNode Tag. They are mainly useful when debugging connection compatibility, connection stability, or mobile BLE stack behavior.
| Field | Value |
|---|---|
| Minimum connection interval | 100 ms |
| Maximum connection interval | 200 ms |
| Slave latency | 0 |
| Supervision timeout | 4 s |
| Bonding | Enabled |
| MITM | Disabled |
| LESC | Disabled |
Step 3: Discover GATT Services and Characteristics
After the BLE connection is established, the app should run GATT service discovery to find the services and characteristics exposed by WisNode Tag.
This step lists the GATT services exposed by WisNode Tag. Some services are required for provisioning and command control, while others are provided for device identification, diagnostics, or firmware information.
GATT Services Overview
| Service | UUID | Purpose |
|---|---|---|
| Generic Access | 00001800-0000-1000-8000-00805f9b34fb | Device name and appearance |
| Generic Attribute | 00001801-0000-1000-8000-00805f9b34fb | Standard GATT service changed behavior |
| Device Information | 0000180a-0000-1000-8000-00805f9b34fb | Model and manufacturer information |
| Battery | 014c8ccf-c7e6-4bfa-9cfa-c05fe5ea9010 | Battery level indication |
| Sensor | ddc1ff0a-4585-4ed5-b0b0-6afe8092953d | Sensor data read, currently fixed value |
| Wireless Info | ee4958ec-6a5d-4e9c-87d8-b58af1ff848b | Read-only LoRaWAN and device configuration |
| Custom TX CMD | b3880dd0-2a00-4255-aa4d-eb1bd700c42f | Write control commands, up to 64 bytes |
| Custom RX Notify | 358c70b5-e3ec-4d17-9371-f56852cc16a1 | Receive command responses through notify |
| Custom Debug | 9f933827-d628-4588-aa22-ee64fbf2d084 | Read debug and self-inspection data |
| Custom FOTA | 000018f0-0000-1000-8000-00805f9b34fb | Read firmware information only; do not use custom FOTA writes |
Generic Access Service
The Generic Access Service provides standard BLE device identity information.
| Characteristic | UUID | Operations | Description |
|---|---|---|---|
| Device Name | 2a00 | Read / Write | BLE device name |
| Appearance | 2a01 | Rea | Standard BLE appearance value |
Sensor Service
The Sensor Service exposes a read-only sensor data characteristic. Sensor Notify is not enabled in current firmware.
| Characteristic | UUID | Operations | Length |
|---|---|---|---|
| Sensor Data | a28da977-0643-4469-8a2e-a575fdb88d39 | Read | 2 bytes |
Current fixed value:
FF FF
Custom Debug Service
The Custom Debug Service provides read-only debug and self-inspection data.
| Characteristic | UUID | Operations | Format |
|---|---|---|---|
| Dev Debug Info | 003d565b-fed5-4e93-80ce-76eebd2b45a2 | Read | 1 byte |
| Self Inspection | 3890f1f6-59af-4cee-958f-f5c475c05f18 | Read | 11 bytes |
Self Inspection byte order
| Offset | Component |
|---|---|
| 0 | Flash |
| 1 | Reserved |
| 2 | Battery |
| 3 | Reserved |
| 4 | RF LoRa |
| 5 | Reserved |
| 6 | Bootloader |
| 7 | Reserved |
| 8 | Reserved |
| 9 | 6-axis sensor |
| 10 | GNSS |
Custom FOTA Service (Read Only)
The Custom FOTA Service is used only for reading firmware-related information in this API. Do not use the custom FOTA write and notify characteristics for firmware updates.
| Characteristic | UUID | Operations | Notes |
|---|---|---|---|
| Firmware Version | fd84a818-5147-4b41-a1a6-07f123ce2398 | Read | Example: firmware version: X.Y.Z |
| Device Model | 1c7b1922-353e-4b4c-b474-3392ea4aa721 | Read | device model:20 |
| Custom FOTA Write | ffa0 | - | Do not use |
| Custom FOTA Notify | ffa1 | - | Do not use |
For firmware updates, use Nordic DFU. Nordic buttonless DFU is initialized only when the device is charging. Connect the charger before DFU service discovery or DFU operations.
Step 4: Enable Notifications on Custom RX Notify
Before sending commands, enable notifications on Custom RX Notify so that the app can receive command responses from the device.
Optionally, enable indications on Battery Level to receive live battery updates while the BLE connection is active.
Custom RX Notify
| Characteristic | UUID | Operations | Max notify |
|---|---|---|---|
| Dev MSG Notify | 0039f9f7-e86c-4a2f-b612-650358c82d07 | Notify | 64 bytes |
Step 5: Optionally Enable Battery Level Indications
Optionally, enable indications on Battery Level to receive live battery updates while the BLE connection is active.
| Characteristic | UUID | Operations | Max length |
|---|---|---|---|
| Battery Level | 264607e0-63b9-431e-95ae-b359a00e0141 | Indicate | 20 bytes |
The firmware sends a battery indication about every 1 second while BLE is connected.
Battery Indication Payload Format
The Battery Level characteristic sends the battery status as an ASCII string.
battery level:NNN%,C
| Field | Description |
|---|---|
NNN | Battery percentage, encoded as 3 ASCII digits from 000 to 100. |
C | Charging state: 0 = not charging, 1 = charging. |
Example: battery level:090%,1 indicates that the battery level is 90% and the device is charging.
Step 6: Read Device and LoRaWAN Information
Use the standard information services and Wireless Info Service to read device identity, current configuration, and LoRaWAN credentials.
Device Information Service
| Characteristic | UUID | Operations | Value |
|---|---|---|---|
| System ID | 2a23 | Read | Firmware-defined |
| Model Number | 2a24 | Read | Tracker |
| Manufacturer Name | 2a29 | Read | Shenzhen RAKwireless Technology Co., Ltd. |
Wireless Info Service
Service UUID: ee4958ec-6a5d-4e9c-87d8-b58af1ff848b
All characteristics in this service are read-only.
| Characteristic | UUID | Format |
|---|---|---|
| BLE MAC Address | c5a34e99-378e-4285-973e-2d3fa436178a | 12 ASCII hex characters |
| Serial Number | d99d5ddf-639e-4fe5-a055-cec1f07cc55b | 18 ASCII characters |
| DevID and WorkMode | 0720ce09-206e-453e-a969-7b4f3b222ad4 | 32 bytes binary |
| Region Info | 4ae3f275-21fd-49dc-8439-4eeacf698160 | 1 byte |
| DevEUI | ce513904-1558-4750-b341-d406271e4739 | 16 ASCII hex characters |
| AppEUI | 6510b71a-aac3-479a-baa0-7f0b53a6ce71 | 16 ASCII hex characters |
| AppKey | 7328802a-c134-4a8a-8d2b-bf40ff2293c7 | 32 ASCII hex characters |
DevID and WorkMode Format
The DevID and WorkMode characteristic is a 32-byte binary field.
| Offset | Length | Field | Endian | Value / Notes |
|---|---|---|---|---|
| 0 | 1 | Work mode | — | Firmware work mode code |
| 1 | 1 | Region code | — | 0x00: CN470 0x01: US915 0x02: EU868 0x03: AS923-10x04: AS923-20x05: AS923-30x06: AS923-40x07: AU9150x08: IN8650x09: RU8640x0A: KR920 |
| 2 | 2 | Track interval | Big-endian | Tracking interval value |
| 4 | 4 | APPID | Big-endian | Application ID |
| 8 | 4 | DEVID | Big-endian | Device ID |
| 12 | 4 | Last sync UTC | Big-endian | Unix timestamp in seconds |
| 16 | 1 | Alarm level | — | Alarm level value |
| 17 | 1 | LED switch | — | 0x01 = On0x02 = Off |
| 18 | 1 | Buzzer switch | — | 0x01 = On0x02 = Off |
| 19 | 1 | Alarm switch | — | 0x01 = On0x02 = Off |
| 20 | 12 | Reserved | — | Reserved for future use |
Step 7: Send Control Commands
Use Custom TX CMD to write supported control commands to the device.
Custom TX CMD
| Characteristic | UUID | Operations | Max write |
|---|---|---|---|
| Custom TX CMD | fd2348e1-d0fd-45a7-aaf3-b5d911aa4555 | Write | 64 bytes |
Command Write Format
| Offset | Length | Field | Description |
|---|---|---|---|
| 0 | 1 | CMD | Command ID |
| 1 | 1 | X1 | Command parameter |
| 2 | 1 | X2 | Command parameter or reserved |
| 3 | 1 | LEN | Payload length |
| 4 | LEN | Payload | Command payload |
Unless noted otherwise, multi-byte fields use big-endian byte order.
Firmware queues BLE write commands (queue depth 16) and processes them in the main loop.
Command Summary
| CMD | Name | Payload LEN |
|---|---|---|
0x04 | Set indicator switches (LED / buzzer / alarm) | 0x02 |
0x1E | Wake / LED flash trigger | 0x00 |
0x22 | Sync time | 0x05 (typical) |
0x24 | Bind APPID and DEVID | 0x08 |
0x27 | Set LoRaWAN region | 0x00 |
0x29 | Set work mode | 0x00 |
0x2A | Set interval or alarm level | 0x02 |
0x2B | Set phone-assisted location | 0x08 (typical) |
0x2D | Set emergency contact | N (max 32) |
0x2E | Set work mode and interval | 0x02 |
0x33 | BLE link check | 0x00 |
Step 8: Handle Command Responses
After a command is written to Custom TX CMD, the device returns the command response through Custom RX Notify.
Response Format
| Offset | Length | Field | Description |
|---|---|---|---|
| 0 | 1 | Header | Fixed 0xAF |
| 1 | 1 | CMD | Original command ID |
| 2 | 1 | Result | 0x00 = command handler accepted |
| 3 | 1 | LEN | Response payload length |
| 4 | LEN | Payload | Echo of bytes from the original command starting at offset 1 |
-
The firmware sends
Result = 0x00after the command handler returns. -
Unsupported command IDs may still receive
0xAF ... 0x00because the default handler does not return an error code. -
If a command write exceeds 61 bytes, the response may fail because the response payload limit is 60 bytes.
-
A region change response only means the request was accepted. LoRaWAN region switching is completed asynchronously.
Control Command Reference
This section provides detailed usage information for the command IDs listed in Command Summary. All commands are written to Custom TX CMD and use the common command write format described in Command Write Format. Command responses are returned through Custom RX Notify.
Set Indicator Switches
Use the 0x04 command to turn the LED, buzzer, or alarm switch on or off.
Command Payload Format
| Offset | Value | Description |
|---|---|---|
| 0 | 0x04 | Command ID |
| 1 | 0x00 | Reserved |
| 2 | 0x00 | Reserved |
| 3 | 0x02 | Payload length |
| 4 | Module | Target module |
| 5 | Switch | 0x01: On0x02: Off |
Module Values
| Module | Target |
|---|---|
0x01 | LED |
0x02 | Buzzer |
0x03 | Alarm switch |
Response
AF 04 00 05 00 00 02 <Module> <Switch>
Wake / LED Flash
Use the 0x1E command to trigger a green LED flash pattern. This command can be used to visually identify the connected device during provisioning or service operations.
Command Payload Format
| Offset | Value | Description |
|---|---|---|
| 0 | 0x1E | Command ID |
| 1 | 0x00 | Reserved |
| 2 | 0x00 | Reserved |
| 3 | 0x00 | Payload length |
Request
1E 00 00 00
Sync Time
Use the 0x22 command to synchronize the device time.
Command Payload Format
| Offset | Length | Field | Description |
|---|---|---|---|
| 0 | 1 | CMD | 0x22 |
| 1 | 1 | Reserved | Reserved |
| 2 | 1 | Reserved | Reserved |
| 3 | 1 | LEN | Payload length, typically 0x05 |
| 4 | 4 | Local time | Big-endian timestamp |
| 8 | 1 | Timezone offset | Timezone offset in hours, signed int8 |
UTC Calculation
The firmware stores UTC time using the following calculation:
UTC = LocalTime - TimezoneHours × 3600
Bind APPID and DEVID
Use the 0x24 command to bind the device to an application ID and device ID.
Command Payload Format
| Offset | Length | Field | Description |
|---|---|---|---|
| 0 | 1 | CMD | 0x24 |
| 1 | 1 | Reserved | Reserved |
| 2 | 1 | Reserved | Reserved |
| 3 | 1 | LEN | Payload length = 0x08 |
| 4 | 4 | APPID | Big-endian application ID |
| 8 | 4 | DEVID | Big-endian device ID |
The values are persisted by the firmware and can be verified by reading DevID and WorkMode from the Wireless Info Service.
Set LoRaWAN Region
Use the 0x27 command to set the LoRaWAN region used by the device.
Command Payload Format
| Offset | Value | Description |
|---|---|---|
| 0 | 0x27 | Command ID |
| 1 | Region | Region code |
| 2 | 0x00 | Reserved |
| 3 | 0x00 | Payload length |
-
The command is accepted and a response is sent immediately.
-
Region switching runs asynchronously in the main loop.
-
During region switching, LoRaWAN join and uplink are temporarily blocked.
-
Re-read Region Info after a short wait to confirm the final applied region.
Set Work Mode
Use the 0x29 command to set the firmware work mode.
Command Payload Format
| Offset | Value | Description |
|---|---|---|
| 0 | 0x29 | Command ID |
| 1 | Work mode | Work mode code |
| 2 | 0x00 | Reserved |
| 3 | 0x00 | Payload length |
In the TrackIT app, work mode means LoRaWAN or P2P. Battery mode means Static, Monitor, or Movement. The TrackIT battery modes map to firmware work mode codes.
LoRaWAN Work Mode Values
| Code | Firmware name | TrackIT battery mode |
|---|---|---|
0x08 | LoRaWAN node beacon | Monitor mode |
0x09 | LoRaWAN node alarm | Movement mode |
0x0B | LoRaWAN node static | Static mode |
Legacy Work Mode Values
| Code | Work mode |
|---|---|
0x01 | Master |
0x02 | Message |
0x03 | Livetrack |
0x04 | Beacon |
0x05 | Location on demand |
0x06 | Alarm |
0x07 | Relay |
For codes 0x08, 0x09, and 0x0B, the firmware enables GNSS as needed and starts or restarts the LoRaWAN join process.
Set Interval or Alarm Level
Use the 0x2A command to set the track interval or alarm level. The meaning of the value depends on the current work mode.
Command Payload Format
| Offset | Length | Field | Description |
|---|---|---|---|
| 0 | 1 | CMD | 0x2A |
| 1 | 1 | Reserved | Reserved |
| 2 | 1 | Reserved | Reserved |
| 3 | 1 | LEN | Payload length = 0x02 |
| 4 | 2 | Value | Big-endian value |
Firmware Behavior by Current Work Mode
| Current work mode | Firmware behavior |
|---|---|
0x08 LoRaWAN node beacon | Track interval = value alarm level = 3 |
0x09 LoRaWAN node alarm | Track interval = 2 alarm level = value |
0x0B LoRaWAN node static | Track interval = value alarm level = 3 |
In LoRaWAN work modes, firmware restarts the join process after applying the change.
Set Phone-Assisted Location
Use the 0x2B command to write a phone-assisted location to the device.
Command Payload Format
| Offset | Length | Field | Description |
|---|---|---|---|
| 0 | 1 | CMD | 0x2B |
| 1 | 1 | Reserved | Reserved |
| 2 | 1 | Reserved | Reserved |
| 3 | 1 | LEN | Payload length, typically 0x08 |
| 4 | 4 | Latitude integer | Big-endian latitude value |
| 8 | 4 | Longitude integer | Big-endian longitude value |
Coordinate conversion:
integer_value = floor(decimal_degrees × 1,000,000)
Set Emergency Contact
Use the 0x2D command to write emergency contact or SOS-related information to the device.
Command Payload Format
| Offset | Length | Field | Description |
|---|---|---|---|
| 0 | 1 | CMD | 0x2D |
| 1 | 1 | Reserved | Reserved |
| 2 | 1 | Reserved | Reserved |
| 3 | 1 | Contact info length | Length of contact info bytes |
| 4 | N | Contact info bytes | Emergency contact or SOS-related information |
Maximum stored length is 32 bytes, and this data may appear in SOS LoRaWAN uplinks. For SOS uplink decoding, refer to the LoRaWAN Payload Reference.
Set Work Mode and Interval
Use the 0x2E command to set work mode and interval or alarm value in one request.
Command Payload Format
| Offset | Length | Field | Description |
|---|---|---|---|
| 0 | 1 | CMD | 0x2E |
| 1 | 1 | Work mode | Work mode code |
| 2 | 1 | Reserved | Reserved |
| 3 | 1 | LEN | Payload length = 0x02 |
| 4 | 2 | Interval or alarm value | Big-endian value |
This command combines the behavior of 0x29 and 0x2A.
Firmware Behavior by Work Mode
| Work mode | Firmware behavior |
|---|---|
0x08 | Track interval = value alarm level = 3 restart join |
0x09 | Track interval = 2 alarm level = value restart join |
0x0B | Track interval = value alarm level = 3 restart join |
BLE link Check
Use the 0x33 command to verify that the BLE command path is working.
Command Payload Format
| Offset | Value | Description |
|---|---|---|
| 0 | 0x33 | Command ID |
| 1 | 0x00 | Reserved |
| 2 | 0x00 | Reserved |
| 3 | 0x00 | Payload length |
Request:
33 00 00 00
Response:
AF 33 00 03 00 00 00
Integration Notes and Constraints
This section lists command behaviors and feature constraints that developers should consider when integrating with the WisNode Tag BLE API.
Commands Not to Rely On
Some command IDs are present in the firmware but are not intended for customer integration. They may use empty or default handlers and may still return a generic 0xAF ... 0x00 response.
Do not rely on these commands unless support is explicitly documented in a future firmware release.
| CMD | Current behavior |
|---|---|
0x0C | Empty handler. It may still return a generic success response. |
| Other unsupported IDs | Default handler path. They may still return a generic success response. |
Features Outside This API
| Feature | Guidance |
|---|---|
| EPO transfer over BLE | Not enabled for customer BLE integration. Do not implement or rely on EPO transfer over BLE. |
Custom FOTA packet protocol (FFA0 / FFA1) | Do not use the custom FOTA write or notify characteristics for firmware updates. Use Nordic DFU instead. |
| Nordic DFU | Nordic buttonless DFU is initialized only when the device is charging. Connect the charger before DFU service discovery or DFU operations. |
