Docs
CoAP
Constrained Application Protocol (CoAP) is a simple protocol with low overhead, designed for devices with constrained resources such as wireless sensors operating on a battery. The Blockbax Platform provides a native integration to publish measurements over CoAP using a pre-shared key (PSK) for encryption, authentication and authorization. To connect your CoAP device the following configuration can be used:
| Property | Value |
|---|---|
| CoAP server URL | coaps://coap.blockbax.com |
| Port number | 5684 (default CoAP port) |
| User identity | The public part of your pre-shared key and can be suffixed if you want to reuse a key for multiple connections. Only one connection is allowed per identity, when a connection already exists for an identity when a new connection is attempted, the existing client is disconnected. |
| Pre-shared key | The secret part of your pre-shared key |
| URL Path | /v0/projects/<YOUR_PROJECT_ID>/measurements. Note: Your project ID can be found in the URL when you open your project in the web app, e.g. app.blockbax.com/projects/40edc099-7a41-4af3-9fa4-2fa4ac23a87a/ |
| Request method | POST |
| Content type | application/json |
| Inbound Connector Id | Supplied as a query parameter, e.g. inboundConnectorId=<INBOUND_CONNECTOR_ID>. Note: this is optional, not supplying an inbound connector id will let it go to the default inbound connector. |
The body of the POST request is identical to the HTTP API. An example can be found in the HTTP API documentation.
An example of a valid request using the libcoap CLI client looks like as follows:
coap-client -u <USER_IDENTITY> -k <PRE_SHARED_KEY> -m post -t "application/json" -f ./measurements.json "coaps://coap.blockbax.com/v0/projects/40edc099-7a41-4af3-9fa4-2fa4ac23a87a/measurements?inboundConnectorId=b5cd5f0a-e33c-4e55-85db-042536758e52"
Inbound connectors
Inbound connectors are integrations to ingest measurements into the Blockbax Platform. In the case of CoAP, there is a default connector that can be reached by posting to this end-point:
coaps://coap.blockbax.com/v0/projects/<PROJECT_ID>/measurements
This end-point expects measurements in the format described in our API reference documentation.
If the payload format is different from the default format, you can use a custom inbound connector. A custom inbound connector has a payload conversion script that is defined as a plain JavaScript function. A dedicated page about payload conversion describes how to develop such a function. This also allows you to log certain things about your payload. A custom inbound connector can be reached at the following end-point:
coaps://coap.blockbax.com/v0/projects/<PROJECT_ID>/measurements?inboundConnectorId=<INBOUND_CONNECTOR_ID>"
The following configuration options are available:
| Field | Description |
|---|---|
| State | Active or Inactive |
| Name | A descriptive name to recognize and find your inbound connector |
| Auto-create subjects | Automatically creates a subjects based on the incoming payload |
Auto-create subjects
Measurements are mapped to subjects and metrics by so-called ingestion IDs. By default, an ingestion ID is derived from the subjects’ external ID and the metrics’ external ID (e.g. MyCar$Location). You can also override this default with a custom ingestion ID. If a measurement with an unknown ingestion ID is encountered, Blockbax tries to find a single metric with an external ID equal to the part after the dollar sign. If this is successful, a subject will be created with an external ID equal to the part before the dollar sign. For example, for the ingestion ID MyCar$Location a subject with external ID MyCar will be created if the metric with external ID Location can be linked to exactly one subject type.