Navigating Data

Before you can access your data, you first have to know what data you are interested in. In the BACE system your data is structured in such a way that it offers maximum flexibility without loosing access simplicity. There are three main components to this structure:

1. Groups

2. Physical Devices

3. Data Sessions Data sessions are only applicable for users of BACE Go and are explained in a separate section. Not sure what device you have? Take a look here!

Navigating Groups

Every BACE Connectivity Module is linked to a group. Groups are data containers; when the BACE Connectivity Module receives data, it is relayed and stored in the respective group. Groups therefore provide access to the data of your Connectivity Module and any device that is connected to it.

Groups can be identified by their unique id_group. A list of groups that you have access to can be retrieved using the group endpoint:

Index groups

GET https://dashboard.bace-iot.com/api/v2/group/index

Respond will consist of a list of your data groups

200: OK

{
    "items": [
        {
            "id": "0fcf513b-...",
            "id_group": "0fcf513b-...",
            "label": "Demo Group",
            "type": "5003",
            "type_label": "Loose Device",
            "subtype": "activity-monitors",
            "id_country": "b8415b65-...",
            "created_at": 1633093198,
            "deleted_at": null,
            "_links": {
                "self": {
                    "href": "/api/v2/group/0fcf513b-..."
                },
                "index": {
                    "href": "/api/v2/group/index"
                },
                "data": {
                    "href": "/api/v2/data?filter[id_group]=0fcf513b-..."
                },
                "downsampled_data": {
                    "href": "/api/v2/data-downsampled?filter[id_group]=0fcf513b-..."
                },
                "raw_data": {
                    "href": "/api/v2/data/index?filter[id_group]=0fcf513b-..."
                }
            }
        },
}

In this example the user has access to one group. The API response already provides hints on how to retrieve data from the device(s) in this group. This is explained further in the next section.

Accessing Data

Navigating Physical Devices

Physical devices are any devices in your IoT project. This includes your BACE Connectivity Module, sensors, devices, and other assets that are connected to BACE products.

All physical devices are identified by the unique id_physical_device parameter. Like the group endpoint, a list of accessible physical devices can be retrieved.

List of all Physical Devices

get

Get a list of all Physical Devices available in the system

Query parameters

per-pageintegerOptional

Amount of record you want to get per Page.

pageintegerOptional

Page nr.

fieldsstringOptional

Fields you want to select

Responses

200

A list of all available Physical Devices in the system

get

/api/v2/physical-device

HTTPcURLJavaScriptPython

GET /api/v2/physical-device HTTP/1.1
Accept: */*

200

A list of all available Physical Devices in the system

No content

Let's evaluate how the response looks like for this command. Please note that for ease of reading some filters are applied and the response is truncated so it will look different than what you get.

GEThttps://dashboard.bace-iot.com/api/v2/physical-device?fields=id_physical_device,label,last_data_at

{
    "items": [
        {
            "id_physical_device": "000795be-a92d-4f05-a21a-2d1b7759609a",
            "label": "BACE100",
            "last_data_at": 1655804141,
        },
        {
            "id_physical_device": "00117ccb-5577-4de4-8613-7af314327fe3",
            "label": "BACE101",
            "last_data_at": 1635377064,
        },
        {
            "id_physical_device": "002ab67b-867b-458d-9e11-87f053e003ea",
            "label": "BACE102",
            "last_data_at": 1630579789,
        }
    ]
}

The response above lists three Connectivity Modules assigned to your account and displays unique physical device ID, label and last time Module sent data to Cloud information. In practice it is important to keep a list of all physical device ids in your own database so that you know which device you are working on when you read/write attributes.

Both endpoints in this section can also be used with Advanced Features. In the example below we use expand on group to get an overview of all groups that each physical device is linked to:

Access physical device data

GET https://dashboard.bace-iot.com/api/v2/physical-device?expand=group

Response will be a paginated list of datapoints that are available in the group.

Query Parameters

Name	Type	Description
expand	group

200: OK

{
 {
    "items": [
        {
            "id_physical_device": "007ed6e0-...",
            "serial_hardware": "b8f00...",
            "label": "",
            "id_parent": null,
            "id_group": "b7624b4d-...",
            "id_device_type": "bace-plus-app",
            "id_iot_device": "366ff2e7-...",
            "is_connected": 1,
            "expected_offline_interval": 0,
            "expected_live_status": 0,
            "device_status": 0,
            "connection": "cellular",
            "created_at": 1647955678,
            "last_data_at": 1648044742,
            "signal": 75,
            "commissioned_at": null,
            "calibrated_at": null,
            "reconnected_at": null,
            "bace_software_version": "1.13.0",
            "app_software_version": "1.2.13",
            "archived_serial": null,
            "archived_at": null,
            "archived_by": null,
            "group": {
                "id": "b7624b4d-...",
                "id_group": "b7624b4d-...",
                "label": "BacePlus-001-...",
                "type": "...",
                "type_label": "Loose Device",
                "subtype": "subtype",
                "id_country": null,
                "created_at": 1647963043,
                "_links": {
                    "self": {
                        "href": "/api/v2/group/b7624b4d-..."
                    },
                    "index": {
                        "href": "/api/v2/group/index"
                    },
                    "data": {
                        "href": "/api/v2/data?filter[id_group]=b7624b4d-..."
                    },
                    "downsampled_data": {
                        "href": "/api/v2/data-downsampled?filter[id_group]=b7624b4d-..."
                    },
                    "raw_data": {
                        "href": "/api/v2/data/index?filter[id_group]=b7624b4d-..."
                    }
                }
            },
            "_links": {
                "self": {
                    "href": "https://dashboard.bace-iot.com/api/v2/physical-device/view?id=007ed6e0-..."
                },
                "index": {
                    "href": "https://dashboard.bace-iot.com/api/v2/physical-device/index"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "https://dashboard.bace-iot.com/api/v2/physical-device?expand=group&page=1"
        },
        "first": {
            "href": "https://dashboard.bace-iot.com/api/v2/physical-device?expand=group&page=1"
        },
        "last": {
            "href": "https://dashboard.bace-iot.com/api/v2/physical-device?expand=group&page=1"
        },
        "next": {
            "href": "https://dashboard.bace-iot.com/api/v2/physical-device?expand=group&page=2"
        }
    },
    "_meta": {
        "totalCount": 1,
        "pageCount": 1,
        "currentPage": 1,
        "perPage": 20
    },
    "expand": [
        "latestEvent",
        "group",
        "parent",
        "deviceType",
        "location",
        "iotDevice",
        "deviceInfo",
        "modbusTemplateHistory",
        "currentModbusTemplate",
        "simCard"
    ],
    "labels": {
        "id_physical_device": "Database ID",
        "label": "Label",
        "labelLink": "Label",
        "serial_hardware": "Serial",
        "group.label": "Group",
        "id_group": "Group",
        "id_device_type": "Device Type",
        "parentDevice.displayLabel": "Parent Device"
    },
    "deviceStatuses": {
        "expectedStatuses": [
            "ALWAYS_OFF",
            "ALWAYS_ON"
        ],
        "availableStatuses": [
            "EXPECTED_OFF",
            "EXPECTED_ON_DEVICE_ON",
            "EXPECTED_ON_DEVICE_OFF"
        ]
    }

The API example responses already provide hints on how to retrieve data from these devices or groups. This is explained in more detail in the next section.