Device configuration is a process by which a device is set up to work correctly within a set of specified parameters. Genetec Clearance™ includes a set of API endpoints to manage the configuration of devices and they provide a central location to store and distribute configuration data for your devices.
Configurations should normally be updated according to what was saved in the system before uploading files to the system.
Credentials are required to obtain access to the content of a device. You can use Clearance to store and retrieve them.
Adding new credentials
Credentials can be added with a call to the tenant/{tenantId}/configuration/negociate endpoint. See this section for details.
Credentials can be retrieved by performing a request to the /tenant/{tenantId}/credential. A unique identifier is generated using the model’s first two fields (that is, SerialNumber, Manufacturer). Therefore, these fields must always be the same values for every call to ensure the device is correctly identified. A list containing the current credentials and any other pending credentials are returned. An empty list is returned if no credentials exist.
curl -X POST 'https://clearance-a-device.geneteccloud.com/api/v1-private/tenant/genetec/credential' -H 'accept: text/plain' -H 'Content-Type: application/json' -d '{ \
"DeviceId": { \
"SerialNumber": "1234", \
"Manufacturer": "genetec", \
"Model": "clearance", \
"CommonName": "guide-1" \
}, \
"DeviceType": "BodyWornCamera" \
}'If you notice that one of the received credentials is invalid, you can communicate it to the system by invoking the /tenant/{tenantId}/credential/failed endpoint.
curl -X POST 'https://clearance-a-device.geneteccloud.com/api/v1-private/tenant/genetec/credential/failed' -H 'accept: text/plain' -H 'Content-Type: application/json' -H 'Authorization: Bearer <some_token>' -d '{ \
"DeviceId": { \
"SerialNumber": "1234", \
"Manufacturer": "genetec", \
"Model": "clearance", \
"CommonName": "guide-1" \
}, \
"Credentials": [ \
{ "DeviceCredential": "credential-1" } \
] \
}'Configuration negotiation
The API provides two different ways to attach data to a device: Capabilities and Configuration. Capabilities are commonly used by devices to share some intricate information to the system. For example, you can use them to indicate the amount of space available on a device. You can also use the Configuration field to push updates to your devices.
Adding or updating a configuration requires what we call a negotiation. It is a two-step process that starts with an initial call to the /tenant/{tenantId}/configuration/negociate endpoint.
curl -X POST 'https://clearance-a-device.geneteccloud.com/api/v1/tenant/genetec/configuration/negociate' -H 'accept: text/plain' -H 'Content-Type: application/json' -H 'Authorization: Bearer <some_token>' -d '{ \
"DeviceId": { \
"SerialNumber": "1234", \
"Manufacturer": "genetec", \
"Model": "clearance", \
"CommonName": "guide-1" \
}, \
"DeviceType": "BodyWornCamera", \
"Capabilities": { \
"some": "data" \
}, \
"Configuration": { \
"some": "configuration" \
}, \
"Credential\": { \
"DeviceCredential": "some_credentials_to_update" \
} \
}'Capabilities
Capabilities are updated right away. Any call to configuration/negociate overwrites the current capabilities.
If the current configurations are exactly the same as the one stored on the server, a 304 Not Modified status code is returned. Otherwise, the expected configuration and a transaction ID will be returned. If the device is able to apply these configurations, you must then commit the transaction. Committing a transaction is the only way for the configuration to become effective. To do so, perform the following operation:
curl -X POST 'https://clearance-a-device.geneteccloud.com/api/v1/tenant/genetec/configuration/commit' -H 'accept: text/plain' -H 'Content-Type: application/json' -H 'Authorization: Bearer <some_token>' -d '{ \
"DeviceId": { \
"SerialNumber": "1234", \
"Manufacturer": "genetec", \
"Model": "clearance", \
"CommonName": "guide-1" \
}, \
"TransactionId": "1234ABC" \
}'TransactionId
Use the TransactionId received with the expected configuration.
If the device cannot apply the configurations, the device must call the reject endpoint with a ReasonCode and a ReasonMessage identifying the reason of the failure.
curl -X POST 'https://dems-dev-eastus-device.azurewebsites.net/api/v1/tenant/genetec/configuration/reject' -H 'accept: text/plain' -H 'Content-Type: application/json' -H 'Authorization: Bearer <some_token>' -d '{ \
"DeviceId": { \
"SerialNumber": "1234", \
"Manufacturer": "genetec", \
"Model": "clearance", \
"CommonName": "guide-1" \
}, \
"TransactionId": "1234ABC" \
"ReasonCode": "er2019", \
"ReasonMessage": "corrupted" \
}'