API

This tutorial is intended for software integrators who perform backend business functions based on the API interface of uBeacon Tools software. Through the API interface, you can obtain the UID, coordinates, power, working status of the Gateway, uBeacon, and Tag devices, as well as the real-time positioning of the Tag. The data format is JSON, and the interface protocols include MQTT, UDP, webhook, HTTP, etc. The software supports deployment on Ubuntu , Windows, MacOs and other platforms.

1.Data Format: JSON

Location data example:

{
    "data": {
        "pos": [
            -3.2616942,
            4.3123593,
            1.1999172
        ], //position：x,y,z
        "posNoise": [
            0.71,
            0.62,
            0.03
        ], //Positioning noise: x,y,z, the larger the value, the lower the confidence.
        "time": 575889100, //Positioning timestamp.
        "vel": [
            -0.08,
            0.1,
            0
        ], //Velocity：x,y,z
        "velNoise": [
            0.13,
            0.13,
            0.01
        ] //Velocity noise：x,y,z, the larger the value, the lower the confidence.
    },
    "deviceName": "T4", //Device name, which is unique within the software.
    "name": "Pos", // Message type
    "uid": "02084a71676424f9e16d"  //Device UID
}

2. Tag positioning API configuration entrance

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

3. Push Tag positioning data through MQTT protocol

api.mqtt.address: {ip or domain name}:{port}

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

api.mqtt.topic: Topic name

4. Push Tag positioning data through UDP protocol

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

5. Push Tag positioning data through webhook protocol

api.hook.url格式: http://{ip or domain name}:{port}/{custom uri}

http method: POST

6. Get device status through HTTP protocol

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

Query parameter:

Parameter name	Parameter type	Parameter description
deviceType	int	Search based on device type. Empty means querying all types of devices, 1 means querying Gateway devices, 2 means querying uBeacon devices, and 3 means querying Tag devices.
online	bool	Depending on whether to search online, empty means querying all statuses, false means querying offline devices, and true means querying online devices.
query	string	Search based on device name prefix or device UID suffix
page	int	Pagination page number, the default is 1, 1 means the first page, and so on.
pageSize	int	The size of each page for paging, the default is 20, the maximum is 100

Response data:

{
    "code": 0, // 0 indicates success, non-0 indicates failure
    "message": "",
    "data": {
        "records": [
          {
            "name": "U6", // Device name
            "type": 2,  // Device type, 1 represents Gateway device, 2 represents uBeacon device, 3 represents Tag device
            "online": false, // Device online status
            "onlineTime": 1727323909, // Online and offline time, online is true to indicate online time, online is false to indicate offline time
            "uid": "0208f5579f8e183fa1eb", // Device UID
            "power": 93, // Device battery percentage
            "coordinate": { // Device coordinates, currently only uBeacon devices have
                "coords": [
                  13.302,  // x-axis
                  12.9,    // y-axis
                  2.9      // z-axis
                ]
             }
           }
    	],
    	"total": 1 // Total number for current search criteria
    }
}