Driver

Drivers decode binary uplink payloads into JSON and encode JSON commands back into binary downlinks. The Driver endpoints let you list the drivers available to your account, look at a specific driver, and manage your own custom drivers.

Note

POST, PATCH and DELETE apply to custom drivers only. Branded (system) drivers are provided by Actility through the Device Catalog and cannot be created, modified or deleted through the API.

For an introduction to driver types and how a driver is assigned to a device, see Driver Introduction.

Driver identifier

Every driver has a unique id built from three parts:

producerId:moduleId:version

For example actility:adeunis-field-test:1. You use this id in the URL when retrieving, updating or deleting a driver, and in your Flow configuration to select the driver (see Flow).

Retrieve the list of drivers

Use GET /drivers to list the drivers available to your account, including both branded (system) and your own (custom) drivers.

GET /drivers

[
  {
    "id": "actility:adeunis-field-test:1",
    "name": "Adeunis Field Test",
    "producerId": "actility",
    "moduleId": "adeunis-field-test",
    "version": "1.0.0",
    "source": "system",
    "type": "thingpark-x-js",
    "private": false,
    "application": {
      "producerId": "adeunis",
      "moduleId": "field-test",
      "version": "1"
    }
  }
]

Filtering and pagination

You can narrow the results with the following optional query parameters:

Parameter	Description
q	Free-text search across drivers.
source	Filter by origin: custom or system.
provider	Filter by driver producer/provider.
manufacturer	Filter by device manufacturer.
protocolId	Filter by driver protocol ID.
page	Page number (starts at 1).
perPage	Number of items per page (default 5000, maximum 5000).

For example, to list only your custom drivers:

GET /drivers?source=custom

The response includes pagination headers such as X-Total, X-Total-Pages, X-Page, X-Per-Page, X-Next-Page and X-Prev-Page to help you iterate over large result sets.

Retrieve a single driver

Use GET /drivers/{driverId} to get the full representation of one driver, including its source code.

GET /drivers/myprovider:mydriver:1

{
  "id": "myprovider:mydriver:1",
  "name": "My driver",
  "description": "My driver description",
  "producerId": "myprovider",
  "moduleId": "mydriver",
  "version": "1.0.0",
  "source": "custom",
  "type": "thingpark-x-js",
  "private": false,
  "application": {
    "producerId": "applicationProvider",
    "moduleId": "applicationModule",
    "version": "1"
  },
  "code": "ZnVuY3Rpb24gZGVjb2RlVXBsaW5rKGlucHV0KXsgcmV0dXJuICJ0ZXN0IiB9"
}

Create a custom driver

Use POST /drivers to create your own driver. This is the endpoint to use when you want to add support for a device that is not covered by an existing branded driver.

The request body must contain:

Field	Required	Description
name	Yes	Human-readable name of the driver.
type	Yes	Driver type. Use thingpark-x-js for a JavaScript driver.
moduleId	Yes	Module identifier used to build the driver id.
version	Yes	Driver version used to build the driver id.
application	Yes	Application descriptor (producerId, moduleId, version).
code	Yes	The driver source code, Base64-encoded.
description	No	Free-text description.
examples	No	Sample uplink/downlink payloads used to document and test the driver.

POST /drivers

{
  "name": "My driver",
  "description": "My driver description",
  "moduleId": "mydriver",
  "version": "1.0.0",
  "type": "thingpark-x-js",
  "application": {
    "producerId": "applicationProvider",
    "moduleId": "applicationModule",
    "version": "1"
  },
  "code": "ZnVuY3Rpb24gZGVjb2RlVXBsaW5rKGlucHV0KXsgcmV0dXJuICJ0ZXN0IiB9",
  "examples": [
    {
      "description": "decode uplink containing three measurements",
      "type": "uplink",
      "bytes": "001f01011f01020a",
      "fPort": 1,
      "time": "2021-08-02T20:00:00.000+05:00",
      "data": {
        "temperature": 79.37,
        "humidity": 79.37,
        "pulseCounter": 10
      }
    }
  ]
}

On success the API returns 201 Created with the full driver, including its generated id and source set to custom.

Note

The code field is your JavaScript driver source encoded in Base64. For guidance on writing the decode/encode functions, follow the IoT Flow Driver Developer Guide.

Update a custom driver

Use PATCH /drivers/{driverId} to modify an existing custom driver. The request uses JSON Merge Patch, so send only the fields you want to change with the Content-Type: application/merge-patch+json header.

PATCH /drivers/myprovider:mydriver:1
Content-Type: application/merge-patch+json

{
  "description": "Updated description",
  "code": "ZnVuY3Rpb24gZGVjb2RlVXBsaW5rKGlucHV0KXsgcmV0dXJuICJ2MiIgfQ=="
}

The response returns the full representation of the updated driver.

Delete a custom driver

Use DELETE /drivers/{driverId} to remove one of your custom drivers.

DELETE /drivers/myprovider:mydriver:1

A successful deletion returns 204 No Content.