Meshcube v6.0.1.5 API

HTTP APIs allow to communicate with MeshCube using the HTTP request-response communication protocol.

In this type of communication the standard request is:

http(s)://<URL>[:port]/<request_type>

Authentication

The system provides three options for authenticating calls from external clients:

  1. No Auth
    The system does not require any authorization. This mode is only suitable for system installed on-premises and thus running in a private network.

  2. Basic Auth
    The system requires the Basic Authentication for API invocation.
    When used combined with a Secure connection, this method provides a good protection against unauthorized accesses with the minimum overhead possible.

  3. JWT Token Auth
    The system requires a JWT Token for API invocation.
    The tokens generated by MeshCube allow to configure:

    • An optional expiry date
    • An optional list of IP Addresses who are allowed to invoke APIs.
    • What API path are accessible using the token.
    • The maximum number of invocation per hour.

For further details about API authentication, please refer to system documentation

Invoking API via MQTT interface

MeshCube allows to invoke the API using the MQTT interface, to be used in scenarios where the MeshCube is not directly connectable, but is connected to an external MQTT Broker.

The MQTT Interface allows to configure:

  • The request topic

  • The response topic

See the manual for MQTT Interface configuration

Sending an API request

Publish to <request-topic> the following payload:

{
  "id": `(string) client generated unique identifier`,
  "method": `(string) the HTTP method`,
  "target": `(string) the API target url`,
  "parameters": `(object) the query string parameters [optional]`,
  "headers": `(object) the request headers [optional]`,
  "body": `(object) the request body [optional]`
}

id

The unique string identifier that must be generated by the client.

Usually an UUID is the best option.

method

The HTTP Method. Must be set according to the API definition

target

The API target url. Must be set according to the API definition

parameters

The API Query string parameters. Should be set when expected.

headers

The API headers. Should be set when expected.

body

The API body request. Should be set when expected, for example in POST APIs.

Receiving the response

MeshCube processes the request

{
    "id":`(string) client generated unique identifier`,
    "timestamp":`(number) the unix timestamp of the API execution`,
    "execution":`(number) the time spent for the API execution`,
    "method": `(string) the HTTP method`,
    "target": `(string) the API target url`,
    "status":`(number) the HTTP status code`,
    "type":`(string) the mime type of the response body [optional]`,
    "body":`(object | string) the response body [optional]`
id

The unique string identifier that must be generated by the client.

Usually an UUID is the best option.

timestamp

The unix timestamp (resolution: milliseconds) of the API execution.

execution

The time that system spent for the API execution

method

The HTTP Method. Must be set according to the API definition

target

The API target url. Must be set according to the API definition

status

The HTTP status of the API response.

type

Omitted when the API does not provides a response body

The content type of the API response body.

body

Omitted when the API does not provides a response body

The response body, encoded as base64, except for:

  • application/json: encoded as JSON element
  • text/plain: encoded as UTF8 string

Responses

In the following are described the responses that are common for all API calls. Other responses will be specified for each call in detail.

Status Code Status Message Body
200 Success Depends on API definition
403 ERR_LICENSE 
The request can not be performed because of a license error		 The JSON license information
500 ERR_SERVER_FAILURE
The server was unable to fulfill the request due to an internal error		 (Optional) Error details as JSON object

Each response status different than 2xx, provides a string identifier as http status message in the form ERR_* in order to identify the error.

For example, a response could provide the status code 400 (bad request) for several scenarios, and the status message will contain the error detail.

API List

GET /api/beacon/anchors

Get information about all the beacon router nodes detected by the system.

This API can be called with FTR Queries. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

[
  {
    "from_cache": false,
    "wrapper_type": "MeshBeaconAnchor",
    "id": <beacon_anchor_id>,
    "node_id": <node_id>,
    "node_address": 9000001,
    "node_network_id": 8369957,
    "node_role": "router_node",
    "beaconing": "ibeacon",
    "ibeacon_uuid": "acfd065ec3c011e39bbe1a514932ac01",
    "ibeacon_major": 9,
    "ibeacon_minor": 1,
    "advertising_interval": 1000,
    "advertising_tx_power": 0,
    "map": {
      "id": 6,
      "description": "Sample Building 1st Floor"
    },
    "position": { ~ },
    "last_update": 1714653185,
    "last_update_time": 40,
    "battery": 3042,
    "status": "online"
  }
]

GET /api/beacon/tags

Get information about all the beacon non-router nodes detected by the system.

This API can be called with FTR Queries. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

[
  {
    "from_cache": false,
    "wrapper_type": "MeshBeaconTag",
    "id": <beacon_tag_id>,
    "node_id": <node_id>,
    "node_address": 10003413,
    "node_network_id": 8369957,
    "node_role": "non_router_node",
    "beaconing": "safety",
    "safety_uuid": "a565cc841e0e4b5ab2d317c98ff5410a",
    "safety_major": 3413,
    "default_advertising_interval": 1000,
    "motion_advertising_interval": 300,
    "alarm_advertising_interval": 100,
    "sleep_advertising_interval": 2500,
    "advertising_tx_power": 0,
    "last_update": 1714653102,
    "last_update_time": 28,
    "battery": 2922,
    "status": "online"
  }
]

GET /api/beacons

Get information about all the beacon nodes detected by the system.

This API can be called with FTR Queries. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

[
  {
    "from_cache": false,
    "wrapper_type": "MeshBeaconAnchor",
    "id": <beacon_id>,
    "node_id": <node_id>,
    "node_address": 9000001,
    "node_network_id": 8369957,
    "node_role": "router_node",
    "beaconing": "ibeacon",
    "ibeacon_uuid": "acfd065ec3c011e39bbe1a514932ac01",
    "ibeacon_major": 9,
    "ibeacon_minor": 1,
    "advertising_interval": 1000,
    "advertising_tx_power": 0,
    "map": {
      "id": 6,
      "description": "Sample Building 1st Floor"
    },
    "position": { ~ },
    "last_update": 1714655173,
    "last_update_time": 29,
    "battery": 3042,
    "status": "online"
  },
  {
    "from_cache": false,
    "wrapper_type": "MeshBeaconTag",
    "id": <beacon_id>,
    "node_id": <node_id>,
    "node_address": 20003421,
    "node_network_id": 8369957,
    "node_role": "non_router_node",
    "beaconing": "safety",
    "safety_uuid": "a565cc841e0e4b5ab2d317c98ff54114",
    "safety_major": 3421,
    "default_advertising_interval": 1000,
    "motion_advertising_interval": 300,
    "alarm_advertising_interval": 100,
    "sleep_advertising_interval": 2500,
    "advertising_tx_power": 0,
    "last_update": 1714655133,
    "last_update_time": 70,
    "battery": 2970,
    "status": "online"
  }
]

GET /api/event-listener

This request is used to generate a Listener that retrieves the Events generated by the system.

The request generates a token that has to be used in the /api/events/{token} to be able to receive the events.

Parameters

If no parameters are added, the Listener retrieves all the events generated by the system and devices. Otherwise it is possible to specify one or more events to listen to.

In addition, it is possible to specify the timeout of the token, i.e., the validity of the token in seconds.

Key Value Optional
events Event(s) name ✓
timeout Value in seconds ✓
Request example

localhost/api/event-listener?events=meshNonRouterNodesDetectionUpdate,meshSensorDataUpdated&timeout=60

Responses

Status Code Status Description Description
200 OK n/a

Response Example

{
  "token": <token>
}

GET /api/events/{token}

This request is used to fetch the Events generated by the system.

The request needs the token generated by /api/getEvents request.

URL Parameters

Key Description
token The token generated by the api /api/event-listener

Responses

Status Code Status description Description
200 OK The response will contain an array of events generated by the system
400 ERR_MISSING_TOKEN No token was specified in the request
404 ERR_LISTENER_NOT_FOUND The listener associated to the token does not exist or is expired

Response Example

[
    {
        "id": <eventID>,
        "sequence_number": 6139,
        "timestamp": 1708613562059,
        "data": {<event_data>}
    },
    {
        "id": <eventID>,
        "sequence_number": 6140,
        "timestamp": 1708613563015,
        "data": {<event_data>}
    }
]

POST /api/gateway/{id}

This API allows to invoke the internal API of a gateway connected to the system using the "Remote control" option.

Note 1 Use this API carefully. For example, disabling the remote Control on the Gateway will break this API.

Note 2 The documentation about BlueUp Gateway APIs are available on BlueUp Docs.

URL Parameters

Key Description
id The gateway id

Body request example

{
  "timeout": 10, // Optional (default: 10), unit: Seconds,
  "method": "GET | POST | DELETE", // The http method
  "target": "api/system", // The Gateway API target url,
  "body": {} // The request body (could be optional or mandatory, depending on the API)
}

Responses

Status Code Status Description Description
503 ERR_MQTT_BROKER_NOT_RUNNING The MQTT Mesh Broker is not connected/configured
503 ERR_MQTT_INTERFACE_DISCONNECTED The MQTT Mesh Client was not connected when attempting to invoke the API
503 ERR_MQTT_PUBLISH_ERROR The MQTT Mesh Client was not able to publish the request on the MQTT Broker
408 ERR_TIMEOUT The system did not receive a response within the timeout value set
404 ERR_GATEWAY_NOT_FOUND The target Gateway was not found
400 ERR_MISSING_REQUEST_BODY No body was passed to the request
400 ERR_MISSING_BODY_PARAMETER One or more required parameters was not included in the request body
xxx Specific Gateway response The Gateway response

GET /api/gateways

Get information about all the gateways connected to the system.

This API can be called with FTR Queries. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK The response contains an array of gateways connected to the system with related information

Response Example

[
    {
        "id": <gateway_id>,
        "model": <gateway_model>,
        "blueup_device": true,
        "device_type": "tinygateway",
        "device_variant": "eth", #available variants for TinyGateway gateways are WiFi, Ethernet, LTE
        "ip_address": <gateway_ip>,
        "sink_id": "sink0",
        "sink_on": true,
        "node_address": 1,
        "network_address": 31415,
        "network_channel": 6,
        "fw_version": "1.5.1.284",
        "www_version": "1.7.0.18",
        "os_version": "4.4.6",
        "api_version": 2,
        "diagnostics_interval": 60,
        "seq_app_config": 6,
        "has_app_config": true,
        "last_update_time": 17,
        "last_update": 1713796401,
        "is_running": true
    }
]

GET /api/map/{id}/anchors

Get all anchors set on a map

GET /api/maps

Get information about all the nodes detected by the system.

This API can be called with FTR Queries. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK The response contains an array of maps setup in the system with related information

Response Example

[
    {
        "id": 2,
        "description": "BlueUp office",
        "pixel_per_mt": 47,
        "z": 0,
        "gps_coordinates": false,
        "image": {
            "id": <image_id>,
            "type": "image/png",
            "url": <image_url>,
            "size": 270220,
            "width": 883,
            "height": 649
        },
        "offset": {<map_origin_coordinates>},
        "area": {
            "vertexes": [<map_vertexes>]
        },
        "zones": [
            {
                "id": "meeting-room",
                "description": "Meeting room",
                "color": "#4169E1",
                "z": 0,
                "vertexes": [<zone_vertexes>]
            },
            {
                "id": "management",
                "description": "Management",
                "color": "#a9e141",
                "z": 0,
                "vertexes": [<zone_vertexes>]
            }
        ],
        "guides": [<array_of_guides>],
        "placeholders": [
            {
                "id": "752851da-63a4-4305-820a-590daac6cc1a",
                "number": 47,
                "color": "#740af5",
                "position": {
                    "x": 15.17,
                    "y": 5.65,
                    "z": 0
                }
            }
        ]
    }
]

GET /api/mesh-packets.db

Get The mesh packets database file

GET /api/network/{address}

API that retrieves the network configurations for the specific network address.

URL Parameters

Key Description
address The network address

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found

Response Example

[
    {
        "address": 12345678,
        "description": <network_description>,
        "active": <active_configuration_id>,
        "templates": [
            {
                "id": <configuration_id>,
                "description": <configuration_description>,
                "last_update": <unix-timestamp-milliseconds>,
                "is_editable": true,
                "is_removable": true,
                "setup": {
                    "diagnostics_interval": 300,
                    "configuration": [
                        {
                            "node_class": "F9",
                            "packet_type": "A2",
                            "parameters": {
                                "sensing_interval": 300,
                                "alerts_enabled": true,
                                "off_by_position": false,
                                "beaconing": "disabled"
                            }
                        },
                        {
                            "node_class": "FA",
                            "packet_type": "B2",
                            "parameters": {
                                "default_positioning_interval": 60,
                                "default_timeout": 65,
                                "default_autoscan_enabled": false,
                                "motion_positioning_interval": 10,
                                "motion_timeout": 60,
                                "motion_autoscan_enabled": false,
                                "alarm_positioning_interval": 10,
                                "alarm_timeout": 60,
                                "alarm_autoscan_enabled": false,
                                "sleep_positioning_interval": 3600,
                                "sleep_autoscan_enabled": true,
                                "alerts_enabled": true,
                                "button_enabled": true,
                                "accelerometer_mode": "motion_detection",
                                "motion_threshold": 10,
                                "motion_duration": 1,
                                "beaconing": "disabled"
                            }
                        }
                    ]
                }
            },
            { ~ }

        ]
    }
]

GET /api/network/{address}/{configuration}

API that retrieves a specific configuration for the specific network address.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found
404 ERR_NETWORK_CONFIGURATION_NOT_FOUND The network configuration was not found

Response Example

[
    {
        "address": 12345678,
        "description": <network_description>,
        "active": <active_configuration_id>,
        "templates": [
            {
                "id": <configuration_id>,
                "description": <configuration_description>,
                "is_editable": true,
                "is_removable": true,
                "setup": {
                    "diagnostics_interval": 300,
                    "configuration": [
                        {
                            "node_class": "F9",
                            "packet_type": "A2",
                            "parameters": {
                                "sensing_interval": 300,
                                "alerts_enabled": true,
                                "off_by_position": false,
                                "beaconing": "disabled"
                            }
                        },
                        {
                            "node_class": "FA",
                            "packet_type": "B2",
                            "parameters": {
                                "default_positioning_interval": 60,
                                "default_timeout": 65,
                                "default_autoscan_enabled": false,
                                "motion_positioning_interval": 10,
                                "motion_timeout": 60,
                                "motion_autoscan_enabled": false,
                                "alarm_positioning_interval": 10,
                                "alarm_timeout": 60,
                                "alarm_autoscan_enabled": false,
                                "sleep_positioning_interval": 3600,
                                "sleep_autoscan_enabled": true,
                                "alerts_enabled": true,
                                "button_enabled": true,
                                "accelerometer_mode": "motion_detection",
                                "motion_threshold": 10,
                                "motion_duration": 1,
                                "beaconing": "disabled"
                            }
                        }
                    ]
                }
            },
            { ~ }

        ]
    }
]

POST /api/network/{address}/{configuration}

API that sets a specific configuration for the specific network address.
The configuration has to be specified in the Body of the API call.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Body

{
  "diagnostics_interval": 300,
  "configuration": [
    {
      "node_class": "F9",
      "packet_type": "A2",
      "parameters": {
        "sensing_interval": 300,
        "alerts_enabled": true,
        "off_by_position": false,
        "beaconing": "disabled"
      }
    },
    {
      "node_class": "FA",
      "packet_type": "B2",
      "parameters": {
        "default_positioning_interval": 120,
        "default_timeout": 65,
        "default_autoscan_enabled": false,
        "motion_positioning_interval": 10,
        "motion_timeout": 60,
        "motion_autoscan_enabled": false,
        "alarm_positioning_interval": 10,
        "alarm_timeout": 60,
        "alarm_autoscan_enabled": false,
        "sleep_positioning_interval": 3600,
        "sleep_autoscan_enabled": true,
        "alerts_enabled": true,
        "button_enabled": true,
        "accelerometer_mode": "motion_detection",
        "motion_threshold": 10,
        "motion_duration": 1,
        "beaconing": "disabled"
      }
    }
  ]
}
Acceptable diagnostics intervals
Value Description
0 Disabled
30 30 sec
60 1 min
120 2 min
300 5 min
600 10 min
1800 30 min

Whether the diagnostic interval is disabled, the nodes will not send their diagnostics information, including routing.

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_MISSING_CONFIG_ID The request body does not contain the required data
400 ERR_MISSING_CONFIG_DATA The configuration data is missing
400 ERR_NETWORK_CONFIGURATION_INVALID The passed configuration is not valid
404 ERR_NETWORK_NOT_FOUND The network was not found
400 ERR_NETWORK_CONFIGURATION_READONLY The configuration cannot be changed (readonly)

Response Example

{
  "changed": true
}

DELETE /api/network/{address}/{configuration}

API that deletes a specific configuration for the specific network address.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found
404 ERR_NETWORK_CONFIGURATION_NOT_FOUND The network configuration was not found
400 ERR_NETWORK_CONFIGURATION_ACTIVE The configuration cannot be delete when it is the active one
400 ERR_NETWORK_CONFIGURATION_DEFAULT The default configuration of a network cannot be deleted

GET /api/network/{address}/{configuration}/app-config

API that retrieves the AppConfig of a specific configuration for the specific network address.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found
404 ERR_NETWORK_CONFIGURATION_NOT_FOUND The network configuration was not found

Response Example

Content-Type is text/plain

f9a204012c0100fab2140078000a000a0e100041003c003c0023010a01000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

GET /api/network/{address}/{configuration}/apply

API that applies a specific configuration to the specific network.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found
404 ERR_NETWORK_CONFIGURATION_NOT_FOUND The network configuration was not found
503 ERR_SERVICE_UNAVAILABLE The Mesh Handler is not active

Response Example

{
  "applied": true
}

POST /api/network/{address}/{configuration}/create

Create a new configuration for a specific network address.

The new configuration has to be specified in the Body of the API call.

URL Parameters

Key Description
address The network address
configuration The configuration template identifier

Body

{
  "description": <Configuration_description>,
  "diagnostics_interval": 300,
  "configuration": [
    {
      "node_class": "F9",
      "packet_type": "A2",
      "parameters": {
        "sensing_interval": 300,
        "alerts_enabled": true,
        "off_by_position": false,
        "beaconing": "disabled"
      }
    },
    {
      "node_class": "FA",
      "packet_type": "B2",
      "parameters": {
        "default_positioning_interval": 120,
        "default_timeout": 65,
        "default_autoscan_enabled": false,
        "motion_positioning_interval": 10,
        "motion_timeout": 60,
        "motion_autoscan_enabled": false,
        "alarm_positioning_interval": 10,
        "alarm_timeout": 60,
        "alarm_autoscan_enabled": false,
        "sleep_positioning_interval": 3600,
        "sleep_autoscan_enabled": true,
        "alerts_enabled": true,
        "button_enabled": true,
        "accelerometer_mode": "motion_detection",
        "motion_threshold": 10,
        "motion_duration": 1,
        "beaconing": "disabled"
      }
    }
  ]
}
Acceptable diagnostics intervals
Value Description
0 Disabled
30 30 sec
60 1 min
120 2 min
300 5 min
600 10 min
1800 30 min

Whether the diagnostic interval is disabled, the nodes will not send their diagnostics information, including routing.

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_MISSING_CONFIG_DATA The configuration data is missing
404 ERR_NETWORK_NOT_FOUND The network was not found
400 ERR_NETWORK_CONFIGURATION_ALREADY_EXISTS The configuration already exists

Response Example

The API response will return the above created configuration.

GET /api/networks

This API retrieves the list of all the networks in the MeshCube instance and for each network reports the network configurations.

This API can be called with FTR Queries. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK The response contains an array of networks with related configurations

Response Example

[
    {
        "address": 12345678,
        "description": <network_description>,
        "active": <active_configuration_id>,
        "templates": [
            {
                "id": <configuration_id>,
                "description": <configuration_description>,
                "last_update": <unix-timestamp-milliseconds>,
                "is_editable": true,
                "is_removable": true,
                "setup": {
                    "diagnostics_interval": 300,
                    "configuration": [
                        {
                            "node_class": "F9",
                            "packet_type": "A2",
                            "parameters": {
                                "sensing_interval": 300,
                                "alerts_enabled": true,
                                "off_by_position": false,
                                "beaconing": "disabled"
                            }
                        },
                        {
                            "node_class": "FA",
                            "packet_type": "B2",
                            "parameters": {
                                "default_positioning_interval": 60,
                                "default_timeout": 65,
                                "default_autoscan_enabled": false,
                                "motion_positioning_interval": 10,
                                "motion_timeout": 60,
                                "motion_autoscan_enabled": false,
                                "alarm_positioning_interval": 10,
                                "alarm_timeout": 60,
                                "alarm_autoscan_enabled": false,
                                "sleep_positioning_interval": 3600,
                                "sleep_autoscan_enabled": true,
                                "alerts_enabled": true,
                                "button_enabled": true,
                                "accelerometer_mode": "motion_detection",
                                "motion_threshold": 10,
                                "motion_duration": 1,
                                "beaconing": "disabled"
                            }
                        }
                    ]
                }
            },
            { ~ }

        ]
    }
]

GET /api/network-tree/{network}

API that retrieves the tree structure of the network. This API can be used to inspect the network organization: how the nodes are connected to the sink.

URL Parameters

Key Description
address network address

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NETWORK_NOT_FOUND The network was not found

Response Example

{
  "network": 12345678,
  "items": [
    {
      "type": 1,
      "id": <sink_id>, // type = 1  corresponds to the sink node
      "items": [
        {
          "type": 2,
          "id": <router_node_id>, // type = 2  corresponds to the router node
          "hop_count": 1,
          "radio_installation_quality": 100,
          "radio_installation_errors": 0,
          "items": []
        },
        {
          "type": 2,
          "id": <router _node_id>, // type = 2  corresponds to the router node
          "hop_count": 1,
          "radio_installation_quality": 100,
          "radio_installation_errors": 0,
          "items": [
            {
              "type": 2,
              "id": <router_node_id>, // type = 2  corresponds to the router node
              "parent": <parent_node_id>,
              "quality": 94,
              "power": 4,
              "rssi": -69,
              "hop_count": 2,
              "radio_installation_quality": 100,
              "radio_installation_errors": 0,
              "items": [
                {
                  "type": 3,
                  "id": <non_router_node_id>, // type = 3  corresponds to the non router node
                  "parent": <parent_node_id>,
                  "quality": 100,
                  "power": -20,
                  "rssi": -41,
                  "hop_count": 3
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

DELETE /api/node/{id}

Delete a node from the system, when not more used. The nodes must be not online.

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NOT_FOUND The node id was not found
400 ERR_CANNOT_DELETE_ONLINE_NODE Cannot delete online nodes

GET /api/node/{id}

Get information about the node having a given ID.

Specify the Node ID

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK n/a
404 ERR_NOT_FOUND The node id was not found

Response Example

{
    "from_cache": false,
    "id": <Node_ID>,
    "address": 5003408,
    "network_id": 15074110,
    "device": {<device_id>},
    "version": "3.12",
    "node_class": "FB",
    "operation_mode": "autoscan_tag",
    "alarm": "none",
    "state": "sleep",
    "state_time": 183563,
    "role": "non_router_node",
    "low_latency": false,
    "autorole": false,
    "max_buffer_usage": 2,
    "avg_buffer_usage": 0,
    "routers_in_neighborhood": 1,
    "scans": 237,
    "battery": 2970,
    "nodes": {
        "timestamp": 1708505215,
        "travel_time": 0,
        "count": 1,
        "items": [<nodes_array> ]
    },
    "routing": {<routing_info>},
    "has_configuration": true,
    "configuration_status": "missing",
    "last_update": 1708505246,
    "last_update_time": 97661,
    "last_update_elapsed": {},
    "status": "offline"
}

GET /api/node/{id}/alias

Retrieve the alias set on the node.

Specify the Node ID

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK

Response Example

{
    "id": <nodeID>,
    "alias": <alias>
}

DELETE /api/node/{id}/alias

Delete the alias set on the node.

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_NOT_FOUND The node id was not found

Response Example

{
  "id": <nodeID>,
  "alias": null
}

POST /api/node/{id}/alias

Set the alias to the node.

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Body

{
  "alias": `string`
}

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_NOT_FOUND The node id was not found

Response Example

{
  "id": <nodeID>,
  "alias": <alias>
}

GET /api/node/{id}/group

Retrieve the group set on the node.

Specify the Node ID

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK

Response Example

{
    "id": `string`,
    "group": `string` | null
}

POST /api/node/{id}/group

Set the group to the node.

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Body

{
  "group": `string`
}

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_NOT_FOUND The node id was not found

Response Example

{
  "id": `string`,
  "group": `string` | null
}

DELETE /api/node/{id}/group

Delete the group set on the node.

URL Parameters

Key Description
id Node unique identifier, composed by:
- Node type prefix: S Sink, R Router node, N Non Router node.
- Node address
- Network address

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_NOT_FOUND The node id was not found

Response Example

{
  "id": `string`,
  "group": null
}

GET /api/nodes

Get information about all the nodes detected by the system.

This API can be called with FTR Queries. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK The response contains an array of nodes detected by the system

Response Example

[
    {
        "from_cache": true,
        "id": <sink_id>,
        "address": 1,
        "network_id": 14480430,
        "role": "sink_node",
        "low_latency": true,
        "autorole": false,
        "max_buffer_usage": 0,
        "avg_buffer_usage": 0,
        "routers_in_neighborhood": 9,
        "scans": 8,
        "boot_count": 5,
        "stack_version": "5.3.0.89",
        "app_version": "1.4.0.0",
        "scratchpad_stored_sequence": 0,
        "scratchpad_processed_sequence": 255,
        "is_otap_enabled": true,
        "has_configuration": false,
        "configuration_status": "none",
        "last_update": 1707474364,
        "last_update_time": 1128398,
        "last_update_elapsed": {},
        "status": "none"
    },
    {
        "from_cache": false,
        "id": <router_id>,
        "address": 9000001,
        "network_id": 8369957,
        "device": {<device_info>},
        "version": "3.12",
        "node_class": "F9",
        "operation_mode": "opportunistic_anchor",
        "alarm": "none",
        "state": "default",
        "state_time": 183411,
        "role": "router_node",
        "low_latency": false,
        "autorole": false,
        "max_buffer_usage": 0,
        "avg_buffer_usage": 0,
        "routers_in_neighborhood": 2,
        "scans": 128,
        "battery": 3066,
        "routing": {<routing_info>},
        "has_configuration": true,
        "configuration_status": "matches",
        "last_update": 1708602755,
        "last_update_time": 7,
        "last_update_elapsed": {},
        "status": "online"
    },
    {
        "from_cache": false,
        "id": <non_router_id>,
        "address": 10003412,
        "network_id": 8369957,
        "device": {<device_info>},
        "version": "3.12",
        "node_class": "FA",
        "operation_mode": "nrls_tag",
        "alarm": "none",
        "state": "default",
        "state_time": 617,
        "role": "non_router_node",
        "low_latency": false,
        "autorole": false,
        "max_buffer_usage": 4,
        "avg_buffer_usage": 2,
        "routers_in_neighborhood": 0,
        "scans": 1,
        "battery": 2958,
        "nodes": {
            "timestamp": 1708602712,
            "travel_time": 54,
            "count": 2,
            "items": [<array_of_nodes>]
        },
        "routing": {<routing_info>},
        "has_configuration": true,
        "configuration_status": "matches",
        "last_update": 1708602712,
        "last_update_time": 50,
        "last_update_elapsed": {},
        "status": "online"
    }
]

POST /api/nodes/{network}/{target}/command

Send command to a specific Target in the system belonging to specified network address

A target can be either the node address of a node or the node class. Specifying the node address, the command will be sent with unicast mode, while when passed the node class, the command will be sent with multicast mode to all nodes having such node class.

In Body of the request has to be defined the command to send to the nodes. The supported commands are:

  • Reboot to reboot the device
  • Change node node-class property
  • Button switch to enable or disable the button
  • Alert to configure the alarm on the device
  • Alert Off to disable buzzer/vibration/led if they were configured as permanent on in the Alert command
  • Gpio to configure GPIO pins

URL Parameters

Key Description
network The network id
target Either the node address or the node class

Body

Each command requires different data inside the Body.

Reboot body
{
  "type": "reboot"
}

No additional data is required

Change node class

Needs tag firmware 4.0 or later

{
  "type": "node_class_change",
  "data": {
    "class": `string`
  }
}
# Valid node classes are:
  • F9 (Default Anchor class)
  • FA (Default Asset Tag class)
  • FB (Default Personal Tag class)
  • FC
  • FD
  • FE
  • FF
Button switch body
{
  "type": "button_switch",
  "data": {
    "enabled": `boolean`
  }
}
Alert body

Here is an example of the complete Alarm command to be sent.

{
  "type": "alert",
  "data": {
    "buzzer_period": 2,
    "buzzer_repeats": 20,
    "buzzer_duty_cycle": 50,
    "vibration_period": 2,
    "vibration_repeats": 20,
    "vibration_duty_cycle": 50,
    "led_period": 2,
    "led_repeats": 20,
    "led_duty_cycle": 50,
    "led_sequential": false,
    "led_red": true,
    "led_green": true,
    "led_blue": true,
    "led_0": true,
    "led_1": true,
    "led_2": true,
    "led_3": true
  }
}

The unnecessary parameters in data object can be omitted.

Alert Off body
{
  "type": "alert_off"
}
GPIO body
{
    "type": "gpio",
    "data":{
        "pin": <pin_number>,
        "mode": "reset" | "output" | "input",
        "pullcfg": "pulldown" | "pullup", #only in Input mode
        "send_interval": <number> #range [0; 255]
    }
}

ACK

Firmware 4.3+ also supports ACK. To enable the ACK the value:

{ "ack": true }

has to be added to the request body. When the ack is added to request body, the respose body will be similar to:

{
    "sent_on": 1722353608201,
    "ack": "158fdc6ab3f8bd479596b55eaa6358e2"
}

The system will generate the event meshNodeCommandAck whether the tag received and processed the commad request.

Responses

Status Code Status Description Description
200 OK
400 ERR_MISSING_BODY No body present in the request
400 ERR_INVALID_COMMAND The system is not able to parse the command
500 ERR_SEND_FAILED Failed to send the command to the Sink(s)
503 ERR_SERVICE_UNAVAILABLE The MQTT Broker is not instantiated
503 ERR_NO_GATEWAY_AVAILABLE No gateway is online to receive the request

POST /api/nodes/{network}/command

Send commands in broadcast to all the Nodes in the network.

Note: if more than one network is configured in MeshCube, make sure to specify the right network to send the command to.

In Body of the request has to be defined the command to send to the nodes. The supported commands are:

  • Reboot to reboot the device
  • Button switch to enable or disable the button
  • Alert to configure the alarm on the device
  • Alert Off to disable buzzer/vibration/led if they were configured as permanent on in the Alert command
  • Gpio to configure GPIO pins

URL Parameters

Key Description
network The network id

Body

Each command requires different data inside the Body.

Reboot body
{
  "type": "reboot"
}

No additional data is required

Change node class
{
  "type": "node_class_change",
  "data": {
    "class": `string`
  }
}
# Valid node classes are:
  • F9 (Default Anchor class)
  • FA (Default Asset Tag class)
  • FB (Default Personal Tag class)
  • FC
  • FD
  • FE
  • FF
Button switch body
{
  "type": "button_switch",
  "data": {
    "enabled": `boolean`
  }
}
Alert body

Here is an example of the complete Alarm command to be sent.

{
  "type": "alert",
  "data": {
    "buzzer_period": 2,
    "buzzer_repeats": 20,
    "buzzer_duty_cycle": 50,
    "vibration_period": 2,
    "vibration_repeats": 20,
    "vibration_duty_cycle": 50,
    "led_period": 2,
    "led_repeats": 20,
    "led_duty_cycle": 50,
    "led_sequential": false,
    "led_red": true,
    "led_green": true,
    "led_blue": true,
    "led_0": true,
    "led_1": true,
    "led_2": true,
    "led_3": true
  }
}

The unnecessary parameters in data object can be omitted.

Alert Off body
{
  "type": "alert_off"
}
GPIO body
{
    "type": "gpio",
    "data":{
        "pin": <pin_number>,
        "mode": "reset" | "output" | "input",
        "pullcfg": "pulldown" | "pullup", #only in Input mode
        "send_interval": <number> #range [0; 255]
    }
}

ACK

Firmware 4.3+ also supports ACK. To enable the ACK the value:

{ "ack": true }

has to be added to the request body. When the ack is added to request body, the respose body will be similar to:

{
    "sent_on": 1722353608201,
    "ack": "158fdc6ab3f8bd479596b55eaa6358e2"
}

The system will generate the event meshNodeCommandAck whether the tag received and processed the commad request.

Using the ack allows to check whether the command was received or not by a tag.

Responses

Status Code Status Description Description
200 OK
400 ERR_MISSING_BODY No body present in the request
400 ERR_INVALID_COMMAND The system is not able to parse the command
400 ERR_MISSING_NETWORK_ADDRESS No network address is specified
500 ERR_SEND_FAILED Failed to send the command to the Sink(s)
503 ERR_SERVICE_UNAVAILABLE The MQTT Broker is not instantiated
503 ERR_NO_GATEWAY_AVAILABLE No gateway is online to receive the request

POST /api/nodes/command

Sends a command to Node(s).

Body Parameters

Key Value Optional
mode The send mode (unicast, multicast, broadcast) ✗
network Network ID (if omitted all networks will be impacted) ✓
address The node address using the unicast sending mode ✗
class The node class address using the multicast sending mode ✗
type Command type ✗
data Command data Depends on command type

In Body of the request has to be defined the command to send to the nodes. The supported commands are:

  • Reboot to reboot the device
  • Change node node-class property
  • Button switch to enable or disable the button
  • Alert to configure the alarm on the device
  • Alert Off to disable buzzer/vibration/led if they were configured as permanent on in the Alert command
  • Gpio to configure GPIO pins

Body

Each command requires different data inside the Body.

Reboot body
{
  "type": "reboot"
}

No additional data is required

Change node class
{
  "type": "node_class_change",
  "data": {
    "class": `string`
  }
}
# Valid node classes are:
  • F9 (Default Anchor class)
  • FA (Default Asset Tag class)
  • FB (Default Personal Tag class)
  • FC
  • FD
  • FE
  • FF
Button switch body
{
  "type": "button_switch",
  "data": {
    "enabled": `boolean`
  }
}
Alert body

Here is an example of the complete Alarm command to be sent.

{
  "type": "alert",
  "data": {
    "buzzer_period": 2,
    "buzzer_repeats": 20,
    "buzzer_duty_cycle": 50,
    "vibration_period": 2,
    "vibration_repeats": 20,
    "vibration_duty_cycle": 50,
    "led_period": 2,
    "led_repeats": 20,
    "led_duty_cycle": 50,
    "led_sequential": false,
    "led_red": true,
    "led_green": true,
    "led_blue": true,
    "led_0": true,
    "led_1": true,
    "led_2": true,
    "led_3": true
  }
}

The unnecessary parameters in data object can be omitted.

Alert Off body
{
  "type": "alert_off"
}
GPIO body
{
    "type": "gpio",
    "data":{
        "pin": <pin_number>,
        "mode": "reset" | "output" | "input",
        "pullcfg": "pulldown" | "pullup", #only in Input mode
        "send_interval": <number> #range [0; 255]
    }
}

ACK

Firmware 4.3+ also supports ACK. To enable the ACK the value:

{ "ack": true }

has to be added to the request body. When the ack is added to request body, the respose body will be similar to:

{
    "sent_on": 1722353608201,
    "ack": "158fdc6ab3f8bd479596b55eaa6358e2"
}

The system will generate the event meshNodeCommandAck whether the tag received and processed the commad request.

Responses

Status Code Status Description Description
200 OK n/a
400 ERR_MISSING_BODY No body present in the request
400 ERR_INVALID_COMMAND The system is not able to parse the command
400 ERR_INVALID_SEND_MODE The specified sending mode in not valid
400 ERR_MISSING_NODE_ADDRESS The node address is missing (raises only for unicast sending mode)
400 ERR_INVALID_NODE_CLASS The specified node class is not valid (raises only for multicast sending mode)
500 ERR_SEND_FAILED Failed to send the command to the Sink(s)
503 ERR_SERVICE_UNAVAILABLE The MQTT Broker is not instantiated
503 ERR_NO_GATEWAY_AVAILABLE No gateway is online to receive the request

POST /api/plugin/{id}/configuration

This request allows to change the configuration of one of the plugins setup in the system.

POST Method

Specify the ID of the plugin in the request

URL Parameters

Key Description
id The plugin identifier

Body

In the body the user has to write the desired configuration of the plugin.

Body example to the request of configuration of SystemNotifications plugin

{
    "recipients": [<list of emails> ],
    "notify_system_start_stop": false,
    "notify_gateway_status": true,
    "notify_node_battery_low": true
}

Responses

Status Code Status Description Description
200 OK The response returns the new configuration parameters set to the plugin
400 ERR_MISSING_ID
400 ERR_MISSING_CONFIG
400 ERR_INVALID_CONFIG
400 ERR_PLUGIN_NOT_CONFIGURABLE Error generated in case the plugin does not support configuration
400 ERR_PLUGIN_CONF_DENIED Error generated when the configuration of the plugin has been denied
404 ERR_NOT_FOUND
500 ERR_UPDATE_CONFIG An error occurred when trying to update the configuration

Response Example

{
    "recipients": [<list of emails> ],
    "notify_system_start_stop": false,
    "notify_gateway_status": true,
    "notify_node_battery_low": true
}

GET /api/plugin/{id}/configuration

This request allows to retrieve the configuration of one of the plugins setup in the system.

Specify the ID of the plugin in the request

URL Parameters

Key Description
id The plugin identifier

Responses

Status Code Status Description Description
200 OK
400 ERR_MISSING_ID
400 ERR_PLUGIN_NOT_CONFIGURABLE Error generated in case the plugin does not support configuration
400 ERR_PLUGIN_CONF_DENIED Error generated when the configuration of the plugin has been denied
404 ERR_NOT_FOUND

Response Example

Response example to the request of configuration of SystemNotifications plugin

{
    "recipients": [<list of emails> ],
    "notify_system_start_stop": false,
    "notify_gateway_status": true,
    "notify_node_battery_low": true
}

GET /api/plugins

Get information about all the Plugins present the system.

The response is composed by an array of plugins and for each plugin is specified its ID, description, version and if the plugin is enabled.

Responses

Status Code Status Description Description
200 OK The response contains as array of plugins configured in the system

Response Example

[
  {
    "id": <PluginID>,
    "description": <Plugin description>,
    "version": {
      "major": 1,
      "minor": 0,
      "revision": 0,
      "stage": "release"
    },
    "icon": <icon>,
    "enabled": true
  }
]

GET /api/sensor/{id}/samples

This API allows to retrieve all the samples of a selected sensor, that are stored in the database.

Specify the Sensor ID

Parameters

If no parameters are added, the API call retrieves all the samples stored in the database. Otherwise it is possible to specify some filtering parameters:

Key Value Optional Description
from number ✓ UNIX timestamp of the starting date and time to retrieve data
to number ✓ UNIX timestamp of the stopping date and time to retrieve data
type string ✓ Type of measurement to retrieve:
- temperature (or temp)
- co2
- pressure
- humidity

Responses

Status Code Status Description Description
200 OK The response contains an array of nodes detected by the system

Response Example

Example of the call that retrieves data of temperature and co2 from a sensor. Request:

/api/sensor/SENSOR_R9000008-12345678/samples?type=temp,co2&from=1714428000000

[
    {
        "timestamp": 1714428182169,
        "co2": 665,
        "temperature": 23.4
    },
    {
        "timestamp": 1714428482197,
        "co2": 612,
        "temperature": 23.3
    },
    {
        "timestamp": 1714428782266,
        "co2": 618,
        "temperature": 23.3
    },
    { ~ }
]

GET /api/sensors

Get information about all the sensors present in the system.

This API can be called with FTR Queries. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

[
  {
    "from_cache": false,
    "wrapper_type": "MeshSensor",
    "id": <sensor_id>,
    "alias": <sensor_alias>,
    "node_id": <node_id>,
    "node_address": 9000008,
    "node_network_id": 12345678,
    "node_role": "router_node",
    "temperature": {
      "unit": "celsius",
      "value": 26.9
    },
    "humidity": 52,
    "pressure": 98559,
    "co2": {
      "ppm": 448,
      "classification": "excellent"
    },
    "last_update": 1714488630,
    "last_update_time": 6,
    "battery": 2820,
    "status": "online"
  }
]

POST /api/sensors/configuration

This API allows to set the configuration of the Sensors.

POST method

Body

{
  "temperature_unit": "celsius",
  "data_retention_days": 730
}

Responses

Status Code Status Description Description
200 OK The response contains an array of nodes detected by the system

Response Example

{
  "updated": true
}

GET /api/sensors/configuration

This API allows to retrieve the configuration of the Sensors.

Responses

Status Code Status Description Description
200 OK The response contains an array of nodes detected by the system

Response Example

{
  "temperature_unit": "celsius",
  "data_retention_days": 730
}

GET /api/status

Get all the information about system status.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

{
  "os": {<os_info>},
  "hostname": "blueupbeacons.com",
  "title": "BlueUp Processing Engine v.6.0.0.59",
  "version": "6.0.0.59",
  "system": {
    "code": "meshcube",
    "description": "MeshCube"
  },
  "license": { <license_info>},
  "timestamp": 1709712155206,
  "activated": true,
  "started_on": 1709670440,
  "uptime": { },
  "network": {<network_info>},
  "processors": 2,
  "pressure": {
    "ram": 141,
    "pram": 3.5,
    "pcpu": 0.7
  }
}

GET /api/system

Get the basic information about the BPE system.

Responses

Status Code Status Description
200 OK

Response Example

{
  "id": `string`,
  "uid": `string`,
  "description": `string`,
  "version": `string`
}

GET /api/system/diagnostics

Get all the information about system diagnostics

Responses

Status Code Status Description
200 OK

Response Example

{
  "eventManager": {
    "description": "EventManager",
    "data": {<data>}
  },
  "localStorage": {
    "description": "Local Storage",
    "data": {<data>}
  },
  "httpServer": {
    "description": "Http Server",
    "data": {<data>}
  }
}

GET /api/tag/settings

Get information about tag positioning settings saved in the system.

Responses

Status Code Status Description Description
200 OK n/a

Response Example

{
  "positioning_mode": 0,
  "anchor_rssi_threshold": -80,
  "state_default_update_position": 2,
  "state_default_update_mode": 2,
  "state_motion_update_position": 2,
  "state_motion_update_mode": 1,
  "state_alarm_update_position": 2,
  "state_alarm_update_mode": 1,
  "state_sleep_update_position": 0,
  "state_sleep_update_mode": 2,
  "map_selection_delta_rssi": 5,
  "map_selection_anchor_avg_number": 3,
  "map_selection_delta_avg": 0.5,
  "anchor_group_selection_delta_rssi": 6,
  "anchor_group_selection_anchor_avg_number": 3,
  "anchor_group_selection_delta_avg": 0.5,
  "mesh_anchor_localization_amount_min": 1,
  "mesh_anchor_localization_amount_max": 4
}

Positioning modes

Code Description
0 map-positioning
1 zone-positioning

POST /api/tag/settings

Change tag positioning settings in the system.

POST Method In the body of the request has to be specified the full configuration of tag positioning settings, changing the parameters the user is interested in.

Body

{
  "configuration_level": "basic",
  "remove_timeout": 0,
  "positioning_mode": 0,
  "anchor_rssi_threshold": -100,
  "state_default_update_position": 2,
  "state_default_update_mode": 1,
  "state_motion_update_position": 2,
  "state_motion_update_mode": 1,
  "state_alarm_update_position": 2,
  "state_alarm_update_mode": 1,
  "state_sleep_update_position": 0,
  "state_sleep_update_mode": 1,
  "map_selection_delta_rssi": 5,
  "map_selection_anchor_avg_number": 5,
  "map_selection_delta_avg": 0.5,
  "anchor_group_selection_delta_rssi": 5,
  "anchor_group_selection_anchor_avg_number": 5,
  "anchor_group_selection_delta_avg": 0.5,
  "mesh_anchor_localization_amount_min": 1,
  "mesh_anchor_localization_amount_max": 0
}

Responses

Status Code Status Description Description
200 OK
400 ERR_MISSING_SETTINGS

Response Example

{
  "changed": true
}

GET /api/tags

Get information about all tags present in the system.

The response is an array of the tags present in the system with related information.

This API can be called with FTR Queries. Go to the FTR Queries section for more information.

Responses

Status Code Status Description Description
200 OK The response contains an array of the tags in the system

Response Example

[
  {
    "from_cache": false,
    "wrapper_type": "MeshTag",
    "id": <Tag_id>,
    "alias": "Wearable Tag",
    "node_id": <node_id>,
    "node_address": 10003378,
    "node_network_id": 140114,
    "node_role": "non_router_node",
    "version": "3.12",
    "node_class": "FA",
    "operation_mode": "nrls_tag",
    "alarm": "none",
    "state": "sleep",
    "state_time": 39543,
    "anchors": 4,
    "anchor": [<anchors_array>],
    "positioning_log_enabled": false,
    "positioning_mode": "trilateration",
    "location": {<location_info>},
    "last_update": 1709708841,
    "last_update_time": 3441,
    "battery": 3090,
    "status": "online"
  }
]

GET /api/tags/{network}

Get information about all tags handled by the system belonging to the specified network.

Specify the network ID.

The response contains an array of all the tags in the specified network and the related information.

URL Parameters

Key Value
network Network ID

Responses

Status Code Status Description Description
200 OK The response contains an array of tags detected in the specified network

Response Example

[
    {
        "from_cache": false,
        "wrapper_type": "MeshTag",
        "id": <tag_id>,
        "node_id": <node_id>,
        "node_address": 10003412,
        "node_network_id": 8369957,
        "node_role": "non_router_node",
        "version": "3.12",
        "node_class": "FA",
        "operation_mode": "nrls_tag",
        "alarm": "none",
        "state": "default",
        "state_time": 359,
        "anchors": 0,
        "positioning_log_enabled": false,
        "positioning_mode": "trilateration",
        "last_update": 1708602456,
        "last_update_time": 48,
        "battery": 2958,
        "status": "online"
    },
    {
        "from_cache": false,
        "wrapper_type": "MeshTag",
        "id": <tag_id>,
        "node_id": <node_id>,
        "node_address": 10003413,
        "node_network_id": 8369957,
        "node_role": "non_router_node",
        "version": "3.12",
        "node_class": "FA",
        "operation_mode": "nrls_tag",
        "alarm": "none",
        "state": "default",
        "state_time": 393,
        "anchors": 0,
        "positioning_log_enabled": false,
        "positioning_mode": "trilateration",
        "last_update": 1708602485,
        "last_update_time": 19,
        "battery": 2952,
        "status": "online"
    }
]

GET /api/event-stream

This Event Stream API allows to receive the events generated by the system as push notifications using Server Sent Events (SSE) technology.

The response body will be a stream with the events generated by the system, sent automatically when the event is generated. For more information about events, please check the API » Events panel or the documentation on BlueUp Docs.

Parameters

listen (Optional)

A list of valid event identifiers that the system shall notify. When omitting the parameter listen the system will notify all events.

Example

Url: GET /api/event-stream?listen=gatewayStatusChanged,meshNodeStateChanged

The system will only notify events: gatewayStatusChanged and meshNodeStateChanged

Response Events

  • event contains data of the generated event.
{
    "id": `string`,
    "sequence_number": `number`,
    "timestamp": `number`
    "data": `object`
}

GET /api/log-stream

This Event Stream API allows to receive the logs generated by the system as push notifications using Server Sent Events (SSE) technology.

The response body will contain the list of logs generated by the system, sent automatically when the event is generated. The same logs are also displayed in the MeshCube interface in section Logs -> System

Parameters

None

Example

Url: GET /api/log-stream

The system will notify log messages

Response Events

syslog object contains data of the generated log.

{
  "uid": `string`, // Unique identifier generated from system boot
  "ticks": `number`, // Number of ticks (1 tick = 100 nanosecond) elapsed from 0000-01-01
  "timestamp": `number`, // Unix timestamp (milliseconds)
  "source": `string`, // Application component which generated the message
  "type": `number`, // Message Type. See the table below
  "message": `string` // The Log Message
}

Log types

Type Description
1 Information
2 Warning
4 Error
8 Debug
16 Verbose

GET /api/information-stream

This Event Stream API allows to receive the system status data via Server Sent Events (SSE) technology.
The content of the received data is equal to the result of the API /api/status.

Parameters

interval (optional)

The interval (seconds) used by the system to send data.

Example

Url: GET /api/information-stream?interval=60

The system will send its status every 60 seconds.

Response Events

  • info contains the current system information.
{
  "uuid": <service_uuid>,
  "os": { <os_info> },
  "hostname": "blueupbeacons.com",
  "title": "MeshCube v6.0.0.62",
  "version": "6.0.0.62",
  "system": {
    "code": "meshcube",
    "description": "MeshCube"
  },
  "license": { <license_info> },
  "timestamp": 1714394598573,
  "activated": true,
  "started_on": 1714394595,
  "uptime": {
    "days": 0,
    "hours": 0,
    "minutes": 0,
    "seconds": 2
  },
  "network": { <network_info> },
  "processors": 16,
  "pressure": {
    "ram": 118,
    "pram": 0.1,
    "pcpu": 46.3
  }
}