Interface Protocols

Tag

The tag side currently supports the following communication methods:

• UWB (default)
• UART
• IIC
• BLE (only one-way broadcast of some data)

Communication method is determined by both software and hardware configuration, default is all off. Configuration methods include:

• Software enable: Configured during production or via backend tool
• Hardware enable: Set relevant IO pins to pull-up or pull-down (unconfigured IO defaults to pull-up)

Final enable = software enable || hardware enable, where:

• UART and BLE cannot be enabled simultaneously; if both are enabled, UART is forced
• UART and IIC cannot be enabled simultaneously; if both are enabled, UART is forced
• UART, IIC, and UWB enabled together is invalid
• If none are enabled, UWB is enabled by default (the default case)

UART requires RX_REQ IO for low power processing. If not controlled, it will always wait for serial data, resulting in high power consumption.

If IIC is enabled but no actual IIC master is connected, the pin is left floating, causing leakage—this is a usage issue.

Users can refer to driver example code, which includes serial parsing examples that parse data and print logs.

Backend

uBeacon Tools has built-in API interfaces for backend business functions.

Through the API, you can obtain UID, coordinates, battery level, working status of Gateway, uBeacon, and Tag devices, as well as real-time positioning of Tags. Data format is JSON. Protocols include MQTT, UDP, webhook, HTTP, and the software supports deployment on Ubuntu, Windows, MacOS, etc.

Data Format: JSON

Positioning Data Example:

{
    "data": {
        "mapId": 2, // map id
        "pos": [
            -3.2616942,
            4.3123593,
            1.1999172
        ], // Position: x, y, z
        "posNoise": [
            0.71,
            0.62,
            0.03
        ], // Position noise: x, y, z. Higher value means lower confidence.
        "time": 1752463929264, // Millisecond timestamp
        "cnt": 575889100, // Device timestamp
        "vel": [
            -0.08,
            0.1,
            0
        ], // Velocity: x, y, z
        "velNoise": [
            0.13,
            0.13,
            0.01
        ], // Velocity noise in x, y, z. Higher value means lower confidence.
        "fences": [
            {
                "id": 18,  // Electronic fence id where the tag is located
                "name": "Fence-13", // Electronic fence name
                "userData": {} // User custom data
            }
        ],
        "optPoses": [
            [
                0.71,
                0.62,
                0.03
            ]
        ]  // Output position after adding boundary/wall constraints
    },
    "deviceName": "T4", // Device name, unique in software
    "name": "Pos", // Message type
    "uid": "02084a71676424f9e16d"  // Device UID
}

API Configuration Entry

Open uBeacon Tool software and follow the steps below to enter the configuration page:

Push Data via MQTT

address: protocol://username:password@hostname:port or protocol://hostname:port or hostname:port

Unencrypted protocols supported: mqtt, tcp, ws

Encrypted protocols supported: mqtts, tcps, wss

Example: mqtt://admin:test@192.168.0.15:1883

api.mqtt.clientId: Client identifier, can be empty

api.mqtt.topic: Topic name

Push Data via UDP

api.udp.address: {ip or domain}:{port}

localAddress: Specify local IP address, mainly used when multiple network cards exist to select the desired card

Push Data via Webhook

api.hook.url format: http://{ip or domain}:{port}/{custom uri}

http method: POST

HTTP Get Device Status

URL: GET http://localhost:8088/openapi/v1/devices?deviceType=&online=&query=&page=&pageSize=

Query parameters:

Name	Type	Description
deviceType	int	Search by device type; empty for all, 1 for Gateway, 2 for uBeacon, 3 for Tag
online	bool	Search by online status; empty for all, false for offline, true for online
query	string	Search by device name prefix or device UID suffix
page	int	Page number, default 1, 1 is first page, and so on
pageSize	int	Page size, default 20, max 100

Response data:

{
    "code": 0, // 0 means success, non-0 means failure
    "message": "",
    "data": {
        "records": [
          {
            "name": "U6", // Device name
            "type": 2,  // Device type: 1 for Gateway, 2 for uBeacon, 3 for Tag
            "online": false, // Online status
            "onlineTime": 1727323909, // Online/offline time; online=true means online time, false means offline time
            "uid": "0208f5579f8e183fa1eb", // Device UID
            "power": 93, // Device battery percentage
            "coordinate": { // Device coordinates, currently only for uBeacon
                "coords": [
                  13.302,  // x coordinate
                  12.9,    // y coordinate
                  2.9      // z coordinate
                ]
             }
           }
        ],
        "total": 1 // Total number under current search conditions
    }
}

HTTP Query Electronic Fences on Map

URL: GET http://localhost:8088/openapi/v1/maps/{mapId}/fences

Path parameters:

Name	Type	Description
mapId	uint32	Map id where the fence is

Response data:

{
    "code": 0, // 0 means success, non-0 means failure
    "message": "",
    "data": {
        "records": [
            {
                "id": 11, // Fence id
                "mapId": 2, // Map id
                "name": "Test Fence", // Fence name
                "enable": true, // Fence enabled
                "bounds": [
                    [
                        [
                            19.305483719334006,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            14.511200794018805
                        ]
                    ]
                ], // Fence boundary (holes not supported)
                "leaveBuffer": 0.3, // Only considered left when outside boundary by > leaveBuffer
                "includes": ["d910570506e6d4f7"],// Tag UIDs for which fence is active; empty means all
                "excludes": ["d48475ae51904290"],// Tag UIDs for which fence is inactive; empty means all
                "userData": {} // User custom data
            }
        ]
    }
}

HTTP Search Electronic Fences

URL: GET http://localhost:8088/openapi/v1/fences

Query parameters:

Name	Type	Description
mapId	uint32	Map id where the fence is
query	string	Search by fence name prefix
page	int	Page number, default 1, 1 is first page
pageSize	int	Page size, default 20, max 100

Response data:

{
    "code": 0, // 0 means success, non-0 means failure
    "message": "",
    "data": {
        "records": [
            {
                "id": 11, // Fence id
                "mapId": 2, // Map id
                "name": "Test Fence", // Fence name
                "enable": true, // Fence enabled
                "bounds": [
                    [
                        [
                            19.305483719334006,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            14.511200794018805
                        ]
                    ]
                ], // Fence boundary (holes not supported)
                "leaveBuffer": 0.3, // Only considered left when outside boundary by > leaveBuffer
                "includes": ["d910570506e6d4f7"],// Tag UIDs for which fence is active; empty means all
                "excludes": ["d48475ae51904290"],// Tag UIDs for which fence is inactive; empty means all
                "userData": {} // User custom data
            }
        ],
        "total": 1 // Total number under current search conditions
    }
}

HTTP Query a Specific Electronic Fence

URL: GET http://localhost:8088/openapi/v1/fences/\{id\}

Path parameters:

Name	Type	Description
id	uint32	Fence id

Response data:

{
    "code": 0, // 0 means success, non-0 means failure
    "message": "",
    "data": {
        "mapId": 2, // Map id
        "name": "Test Fence", // Fence name
        "enable": true, // Fence enabled
        "bounds": [
            [
                [
                    19.305483719334006,
                    14.511200794018805
                ],
                [
                    21.019341055303812,
                    14.511200794018805
                ],
                [
                    21.019341055303812,
                    13.554935615509748
                ],
                [
                    19.305483719334006,
                    13.554935615509748
                ],
                [
                    19.305483719334006,
                    14.511200794018805
                ]
            ]
        ], // Fence boundary (holes not supported)
        "leaveBuffer": 0.3, // Only considered left when outside boundary by > leaveBuffer
        "includes": ["d910570506e6d4f7"],// Tag UIDs for which fence is active; empty means all
        "excludes": ["d48475ae51904290"],// Tag UIDs for which fence is inactive; empty means all
        "userData": {} // User custom data
    }
}

HTTP Add Electronic Fence

URL: POST http://localhost:8088/openapi/v1/fences

Body parameters:

Name	Type	Description
name	string	Fence name
enable	bool	Fence enabled
bounds	[][][][]float64	Fence boundary (holes not supported)
leaveBuffer	float64	Only considered left when outside boundary by > leaveBuffer
includes	[]string	Tag UIDs for which fence is active; empty means all
excludes	[]string	Tag UIDs for which fence is inactive; empty means all
userData	Object	User custom data

{
    "mapId": 2, // Map id
    "name": "Test Fence", // Fence name
    "enable": true, // Fence enabled
    "bounds": [
        [
            [
                19.305483719334006,
                14.511200794018805
            ],
            [
                21.019341055303812,
                14.511200794018805
            ],
            [
                21.019341055303812,
                13.554935615509748
            ],
            [
                19.305483719334006,
                13.554935615509748
            ],
            [
                19.305483719334006,
                14.511200794018805
            ]
        ]
    ], // Fence boundary (holes not supported)
    "leaveBuffer": 0.3, // Only considered left when outside boundary by > leaveBuffer
    "includes": ["d910570506e6d4f7"],// Tag UIDs for which fence is active; empty means all
    "excludes": ["d48475ae51904290"],// Tag UIDs for which fence is inactive; empty means all
    "userData": {} // User custom data
}

Response data:

{
    "code": 0, // 0 means success, non-0 means failure
    "message": ""
}

HTTP Update Electronic Fence

URL: PUT http://localhost:8088/openapi/v1/fences/{id}

Path parameters:

Name	Type	Description
id	uint32	Fence id

Body parameters:

Name	Type	Description
name	string	Fence name
enable	bool	Fence enabled
bounds	[][][][]float64	Fence boundary (holes not supported)
leaveBuffer	float64	Only considered left when outside boundary by > leaveBuffer
includes	[]string	Tag UIDs for which fence is active; empty means all
excludes	[]string	Tag UIDs for which fence is inactive; empty means all
userData	Object	User custom data

{
    "name": "Test Fence", // Fence name
    "enable": true, // Fence enabled
    "bounds": [
        [
            [
                19.305483719334006,
                14.511200794018805
            ],
            [
                21.019341055303812,
                14.511200794018805
            ],
            [
                21.019341055303812,
                13.554935615509748
            ],
            [
                19.305483719334006,
                13.554935615509748
            ],
            [
                19.305483719334006,
                14.511200794018805
            ]
        ]
    ], // Fence boundary (holes not supported)
    "leaveBuffer": 0.3, // Only considered left when outside boundary by > leaveBuffer
    "includes": ["d910570506e6d4f7"],// Tag UIDs for which fence is active; empty means all
    "excludes": ["d48475ae51904290"],// Tag UIDs for which fence is inactive; empty means all
    "userData": {} // User custom data
}

Response data:

{
    "code": 0, // 0 means success, non-0 means failure
    "message": ""
}

HTTP Delete Electronic Fence

URL: DELETE http://localhost:8088/openapi/v1/fences/{id}

Path parameters:

Name	Type	Description
id	uint32	Fence id

Response data:

{
    "code": 0, // 0 means success, non-0 means failure
    "message": ""
}