Skip to content

Device Services C SDK Reference

Introduction

This page provides detail on the API provided by the C SDK. A device service implementation will define a number of callback functions, and a main function which registers these functions with the SDK and uses the SDK lifecycle methods to start the service and shut it down. The implementation may also use some of the helper functions which the SDK provides.

In various places information is passed between the SDK and the DS implementation using the iot_data_t type. This is a holder for data of different types, and its use is described in its own page : Use of iot_data_t

Types

devsdk_service_t

This struct represents a running device service. An instance of it is created by calling devsdk_service_new, and this instance should be passed in subsequent sdk function calls.

devsdk_callbacks

This struct type holds pointers to the various callback functions which the device service implementor needs to define in order to do the device-specific work of the service

devsdk_address_t

This is an alias to void*. Implementations should define their own structure for device addresses and cast devsdk_address_t* to pointers to that structure.

devsdk_resource_attr_t

This is an alias to void*. Implementations should define their own structure for device resource information and cast devsdk_resource_attr_t* to pointers to that structure.

devsdk_protocols

This is an opaque structure which holds protocol properties. The devsdk_protocols_properties function is used to find the properties for a particular protocol.

devsdk_error

This structure is used to pass errors back from the device service startup and shutdown functions

Field Type Content
code uint32_t A numeric code indicating the error. Zero is used for success
reason const char * A string describing the error

An instance of devsdk_error with the code field set to zero should be passed by reference when calling startup and shutdown functions

devsdk_device_t

Specifies a device

Field Type Content
name char* The device's name (for logging purposes)
address devsdk_address_t Address of the device in parsed form

devsdk_resource_t

Specifies a resource on a device

Field Type Content
name char* The resource name (for logging purposes)
attrs devsdk_resource_attr_t Resource attributes in parsed form
type iot_typecode_t Expected type of values read from or written to the resource

devsdk_commandrequest

Specifies a resource in a get or put request

Field Type Content
resource devsdk_resource_t* The resource definition
mask uint64_t Mask to be applied (put requests only)

devsdk_commandresult

Holds a value which has been read from a resource

Field Type Content
value iot_data_t* The value which has been read
origin uint64_t Timestamp of the value

The timestamp is specified in nanoseconds past the epoch. It should only be set if one is provided by the device itself. Otherwise the timestamp should be left at zero and the SDK will use the current time.

devsdk_device_resources

A list of device resources available on a device

Field Type Content
resname char* Name of the resource
attributes iot_data_t* String-keyed map of the resource attributes
type iot_typecode_t Type of the data which may be read or written
readable bool Whether this resource is readable
writable bool Whether this resource is writable
next devsdk_device_resources* The next resource in the list, or NULL if this is the last

devsdk_devices

A description of a device or a list of such descriptions

Field Type Content
device devsdk_device_t* The device's name and addressing information
resources devsdk_device_resources* Information on the device's resources
next devsdk_devices* The next device in the list, or NULL if this is the last

Callbacks

Note that each of the callback functions has as its first parameter a void* pointer. This pointer is specified by the implementation when the device service is created, and is passed to all callbacks. It may therefore be used to hold whatever state is required by the implementation.

Required callback functions

devsdk_initialize

This function is called during the service start operation. Its purpose is to supply the implementation with a logger and configuration.

Parameter Type Description
impl void* The context data passed in when the service was created
lc iot_logger_t* A logging client for the device service
config iot_data_t* A string-keyed map containing the configuration specified in the service's "Driver" section

The function should return true to indicate that initialization was successful, or false to abort the service startup - eg if the supplied configuration was invalid or resources were not available

devsdk_create_address

This function should take the protocol properties that were specified for a device, and create an object representing the device's address in a form suitable for subsequent access.

Parameter Type Description
impl void* The context data passed in when the service was created
protocols const devsdk_protocols* The protocol properties for the device
exception iot_data_t** Additional information in the event of an error

If the supplied protocol properties are valid (ie, mandatory elements are supplied and have valid values), the function should return an allocated structure representing the address. Otherwise the function should return NULL, and set *exception to a string (using eg. iot_data_alloc_string) containing an error message.

devsdk_free_address

This function should free a structure that was previously allocated in the devsdk_create_address implementation.

Parameter Type Description
impl void* The context data passed in when the service was created
address devsdk_address_t The object to be freed.

devsdk_create_resource_attr

This function should take the attributes that were specified for a deviceResource, and create an object representing these attributes in a form suitable for subsequent access.

Parameter Type Description
impl void* The context data passed in when the service was created
attributes const iot_data_t* The attributes for the device
exception iot_data_t** Additional information in the event of an error

If the supplied attributes are valid (ie, mandatory elements are supplied and have valid values), the function should return an allocated structure representing the resource within the device. Otherwise the function should return NULL, and set *exception to a string (using eg. iot_data_alloc_string) containing an error message.

devsdk_free_resource_attr

This function should free a structure that was previously allocated in the devsdk_create_resource_attr implementation

Parameter Type Description
impl void* The context data passed in when the service was created
resource devsdk_resource_attr_t The object to be freed

devsdk_handle_get

This function is called when a get (read) request on a deviceResource or deviceCommand is made. In the former case, the request is for a single reading and in the latter, for multiple readings. These readings will be packaged by the SDK into an Event.

Parameter Type Description
impl void* The context data passed in when the service was created
device devsdk_device_t* The name and address of the device to be queried
nreadings uint32_t The number of readings being requested
requests devsdk_commandrequest* Array containing details of the resources to be queried
readings devsdk_commandresult* Array that the function should populate, with results of this request
options iot_data_t* Any options which were specified in this request
exception iot_data_t** Additional information in the event of an error

The readings array will have been allocated in the SDK; the implementation should set the results into readings[0]...readings[nreadings - 1].

Options will be a string-keyed map which contains any options set specifically on this request. In the current implementation these may have been set via query parameters in the URL used to make the request.

The function should return true if all of the requested resources were successfully read. Otherwise, *exception should be allocated with a string value indicating the problem (this will be logged and returned to the caller), and false returned.

devsdk_handle_put

This function is called when a put (write) request on a deviceResource or deviceCommand is made. In the former case, the request is for a single resource and in the latter, for multiple resources.

Parameter Type Description
impl void* The context data passed in when the service was created
device devsdk_device_t* The name and address of the device to be written to
nreadings uint32_t The number of resources to be written
requests devsdk_commandrequest* Array containing details of the resources to be written
values iot_data_t*[] Array of values to be written
options iot_data_t* Any options which were specified in this request
exception iot_data_t** Additional information in the event of an error

If the mask field in an element of the request array is nonzero, the implementation should implement the following:

new-value = (current-value & mask) | request-value

Options will be a string-keyed map which contains any options set specifically on this request. In the current implementation these may have been set via query parameters in the URL used to make the request.

The function should return true if all of the requested resources were successfully written. Otherwise, *exception should be allocated with a string value indicating the problem (this will be logged and returned to the caller), and false returned.

devsdk_stop

The implementation should perform any cleanup necessary before shutdown. At the time that this function is called, the service will be quiescent, ie there will be no new incoming requests.

Parameter Type Description
impl void* The context data passed in when the service was created
force bool An unclean shutdown may be performed if necessary. Long or indefinite timeouts should not occur.

devsdk_callbacks_init

Call this function in order to create a devsdk_callbacks object containing the required callback functions. This may then be passed to the SDK when starting the service

Parameter Type
init devsdk_initialize
gethandler devsdk_handle_get
puthandler devsdk_handle_put
stop devsdk_stop
create_addr devsdk_create_address
free_addr devsdk_free_address
create_res devsdk_create_resource_attr
free_res devsdk_free_resource_attr

Optional callback functions

devsdk_reconfigure

Implement this function in order to allow changes in the device-specific configuration to be made without restarting the service.

Parameter Type Description
impl void* The context data passed in when the service was created
config iot_data_t* The new configuration (contains all elements, not just those which have changed)

devsdk_callbacks_set_reconfiguration

Call this to add your reconfiguration function to the callbacks structure

Parameter Type Description
cb devsdk_callbacks* structure to be modified
reconf devsdk_reconfigure function to add

devsdk_discover

This function is called when a request for discovery is made. This may occur automatically at intervals or due to an external request. The SDK implements locking such that multiple invocations of this function will not be made in parallel.

Implementations should perform a scan for devices, and use the devsdk_add_discovered_devices function to register them.

Parameter Type Description
impl void* The context data passed in when the service was created

devsdk_describe

This is a placeholder function for future use. Its purpose will be to allow automatic generation of device profiles. It is not used in current versions of EdgeX.

Parameter Type Description
impl void* The context data passed in when the service was created
dev devsdk_device_t* The device which is to be described
options iot_data_t* Service specific discovery options map. May be NULL
resources devsdk_device_resources** The operations supported by the device
exception iot_data_t** Additional information in the event of an error

Implementations should populate the resources parameter and return true if it is possible to automatically describe the device. Otherwise return false and set exception.

devsdk_callbacks_set_discovery

Call this to add your discovery functions to the callbacks structure

Parameter Type Description
cb devsdk_callbacks* structure to be modified
discover devsdk_discover device discovery function
describe devsdk_describe device description function, may be NULL (currently unused)

devsdk_add_device_callback

To be notified when a device is added to the system (and assigned to this device service), provide an implementation of this function

Parameter Type Description
impl void* The context data passed in when the service was created
devname char* The name of the new device
protocols devsdk_protocols* The protocol properties that comprise the device's address
resources devsdk_device_resources* The operations supported by the device
adminEnabled bool Whether the device is administratively enabled

devsdk_update_device_callback

To be notified when a device managed by this service is modified, provide an implementation of this function

Parameter Type Description
impl void* The context data passed in when the service was created
devname char* The name of the updated device
protocols devsdk_protocols* The protocol properties that comprise the device's address
state bool Whether the device is administratively enabled

devsdk_remove_device_callback

To be notified when a device managed by this service is removed, provide an implementation of this function

Parameter Type Description
impl void* The context data passed in when the service was created
devname char* The name of the removed device
protocols devsdk_protocols* The protocol properties that comprise the device's address

devsdk_callbacks_set_listeners

Call this to add your add, remove and/or update listener functions to the callbacks structure. Any of the functions may be NULL

Parameter Type Description
cb devsdk_callbacks* structure to be modified
device_added devsdk_add_device_callback device addition listener
device_updated devsdk_update_device_callback device update listener
device_removed devsdk_remove_device_callback device removal listener

devsdk_autoevent_start_handler

Some device types may be configured to generate readings automatically at intervals. Such behavior may be enabled by providing implementations of this function and the stop handler described below. If "AutoEvents" have been defined for a device, this function will be called to request that automatic events should begin. The events when generated should be posted using the devsdk_post_readings function. In the absence of an implementation of this function, the SDK will poll the device via the get handler.

Parameter Type Description
impl void* The context data passed in when the service was created
devname char* The name of the device to be queried
protocols devsdk_protocols* The address of the device to be queried
resource_name char* The resource on which autoevents have been configured
nreadings uint32_t The number of readings requested
requests devsdk_commandrequest* Array containing details of the resources to be queried
interval uint64_t The time between events, in milliseconds
onChange bool If true, events should only be generated if one or more readings have changed

The function should return a pointer to a data structure that will be provided in a subsequent call to the stop handler when this autoevent is t be stopped

devsdk_autoevent_stop_handler

This function is called to request that automatic events should cease

Parameter Type Description
impl void* The context data passed in when the service was created
handle void* The data structure returned by a previous call to the start handler

devsdk_callbacks_set_autoevent_handlers

Call this to add your autoevent management functions to the callbacks structure. Both start and stop handlers are required

Parameter Type Description
cb devsdk_callbacks* structure to be modified
ae_starter devsdk_autoevent_start_handler Autoevent start handler
ae_stopper devsdk_autoevent_stop_handler Autoevent stop handler

Initialisation and Shutdown

These functions manage the lifecycle of the device service and should be called in the order presented here

devsdk_service_new

This function creates a new device service

Parameter Type Description
defaultname char* The device service name, used in logging, metadata lookups and to scope configuration. This may be overridden via the commandline
version char* The version string for this service. This is for information only, and will be logged during startup
impldata void* An object pointer which will be passed back whenever one of the callback functions is invoked
implfns devsdk_callbacks* Structure containing the device implementation functions. The SDK will call these functions in order to carry out its various actions
argc int* A pointer to argc as passed into main(). This will be adjusted to account for arguments consumed by the SDK
argv char** argv as passed into main(). This will be adjusted to account for arguments consumed by the SDK
err devsdk_error* Nonzero reason codes will be set here in the event of errors

The newly created service is represented by an object of type devsdk_service_t, which is returned if the service is created successfully

The SDK modifies the commandline argument parameters argc and argv, removing those arguments which it supports. The implementation may support additional arguments by inspecting these modified values after the create function has been called

devsdk_service_start

Start the device service. Default values for the implementation-specific configuration are passed in here. These must be provided in a string-keyed iot_data_t map. A value named "X" may be over-ridden in the configuration file by an entry for X in the [Driver] section. For dynamically-updatable configuration, set a value for "Writable/X". This will correspond to a configuration file entry in the [Writable.Driver] section and updates may be received by implementing the devsdk_reconfigure function

Parameter Type Description
svc devsdk_service_t* The device service
driverdfls iot_data_t* Default configuration
err devsdk_error* Nonzero reason codes will be set here in the event of errors

devsdk_service_stop

Stop the device service. Any automatic events will be cancelled and the REST API for the device service will be shut down

Parameter Type Description
svc devsdk_service_t* The device service
force bool Force stop. Currently unused but is passed through to the stop handler
err devsdk_error* Nonzero reason codes will be set here in the event of errors

devsdk_service_free

This function disposes of the device service object and all associated resources

Parameter Type Description
svc devsdk_service_t* The device service

Additional functionality

devsdk_usage

This function writes out the commandline options supported by the SDK. It may be useful if a --help option is to be implemented

devsdk_protocols_properties

This function returns a map of properties (keyed on string) for the named protocol.

Parameter Type Description
prots devsdk_protocols* The protocols to search
name char* The name of the protocol to search for

devsdk_protocols_new

This function creates a new protocols object, or adds a property set to an existing one.

Parameter Type Description
name char* The name of the new protocol
properties iot_data_t* The properties of the new protocol
list devsdk_protocols* The protocols object to extend, or NULL to create a new one

devsdk_protocols_dup

This function duplicates a protocols object

Parameter Type Description
e devsdk_protocols* object to duplicate

devsdk_protocols_free

This function disposes of the memory used by a protocols object

Parameter Type Description
e devsdk_protocols* object to free

devsdk_get_secrets

This function returns secrets (credentials) for the service. In insecure mode these will be part of the service configuration, in secure mode they will be retrieved from the secret store (eg, Vault).

The secrets are returned as a string-keyed map. This should be disposed after use using iot_data_free

devsdk_post_readings

This function posts readings to EdgeX. Depending on configuration this may be via REST to core-data or via the Message Bus to various upstream services. The readings are assembled into an Event and then posted

This function may be used in services which implement the autoevent handlers or by any other service where the natural operation is that readings are generated by the device rather than being explicitly requested

Parameter Type Description
svc devsdk_service_t* The device service
device_name char* Name of the device that has generated the readings
resource_name char* Name of the resource (or command) corresponding to this set of readings
values devsdk_commandresult* The readings to be posted

The cardinality of the values array will depend on the resource - if it is a deviceResource there should be a single reading; for a deviceCommand there may be several

devsdk_add_discovered_devices

This function should be called in response to a request for device discovery, but may be called at any time if for a particular device class immediate automatic discovery is appropriate. The function takes an array of devices in order to allow for batching, but it may be called multiple times during the course of a single invocation of discovery if necessary

Parameter Type Description
svc devsdk_service_t* The device service
ndevices uint32_t Number of devices discovered
devices devsdk_discovered_device* Array of discovered devices

devsdk_set_device_opstate

This function can be used to indicate that a device has become non-operational or non-responsive, or that a device has returned from such a state. The SDK will return errors for requests for a device marked non-operational without calling the get or set handler

Parameter Type Description
svc devsdk_service_t* The device service
devname char* The device that has changed state
operational bool The new operational state

devsdk_get_devices

Returns a list of devices registered with this service

Parameter Type Description
svc devsdk_service_t* The device service

The returned list should be disposed after use using devsdk_free_devices

devsdk_get_device

Returns information on a device

Parameter Type Description
svc devsdk_service_t* The device service
name char* The device to query for

The returned device should be disposed after use using devsdk_free_devices

devsdk_free_devices

Frees a devices structure returned by devsdk_get_devices or devsdk_get_device

Parameter Type Description
svc devsdk_service_t* The device service
d devsdk_devices* The device or device list