Skip to content

Ioto API

The Ioto library provides some utility routines and cloud helper functions.

Most of the Ioto API is provided by the following component libraries:

Extensions

Aws AWS Support.
Ioto Ioto control structure.

Functions

intaws(Url *up, cchar *region, cchar *service, cchar *target, cchar *body, ssize bodyLen, cchar *headers, ...)
 Invoke an AWS API request.
intawsPutFileToS3(cchar *region, cchar *bucket, cchar *key, cchar *filename)
 Put a file to AWS S3.
intawsPutToS3(cchar *region, cchar *bucket, cchar *key, cchar *data, ssize dataLen)
 Put a data block to AWS S3.
char *awsSign(cchar *region, cchar *service, cchar *target, cchar *method, cchar *path, cchar *query, cchar *body, ssize bodyLen, cchar *headers, ...)
 Create a set of signed headers to use with AWS SigV4 REST APIs.
Ioto *ioAlloc(void)
 Allocate the Ioto global object.
intioConfig(Json *config)
 User config entry point.
voidioFlushSync()
 Flush pending changes to the cloud.
voidioFree(void)
 Free the Ioto global object.
char *ioGet(cchar *key)
 Get a value from the Ioto cloud key/value Store.
char *ioGetConfig(cchar *key, cchar *defaultValue)
 Convenience routine to get a value from the Ioto configuration files.
doubleioGetNum(cchar *key)
 Get a numeric value from the Ioto cloud key/value Store.
cchar *ioGetShadow(cchar *key, cchar *defaultValue)
 Get a value from the shadow state.
voidioInit(void)
 Initialize Ioto.
voidioRestartWeb(void)
 Restart the web server.
voidioSaveShadow(void)
 Save the shadow state immediately.
voidioSet(cchar *key, cchar *value)
 Set a string value in the Ioto cloud key/value Store.
voidioSetMetric(cchar *metric, double value, cchar *dimensions, int elapsed)
 Set a metric value in the Ioto cloud.
voidioSetNum(cchar *key, double value)
 Set a numeric value in the Ioto cloud key/value Store.
voidioSetShadow(cchar *key, cchar *value, bool save)
 Set a key value in the shadow.
intioStart(void)
 User start entry point.
voidioStop(void)
 User stop entry point.
voidioSync(bool guarantee)
 Sync all items to the cloud.
voidioTerm(void)
 Terminate Ioto.
char *mqttRequest(Mqtt *mq, cchar *data, Ticks timeout, cchar *topic, ...)
 Issue a MQTT request and wait for a response.
voidmqttRequestFree(Mqtt *mq, cchar *topic, ...)
 Free MQTT subscriptions created by mqttRequest.

Typedefs

Defines

#defineIO_CERTIFICATE   "ioto.crt"
 Name of the AWS thing certificate file.
#defineIO_CONFIG_FILE   "ioto.json5"
 Primary Ioto config file.
#defineIO_DEVICE_FILE   "device.json5"
 Name of the device identification config file.
#defineIO_KEY   "ioto.key"
 Name of the AWS thing key file.
#defineIO_LOCAL_FILE   "local.json5"
 Development overrides.
#defineIO_LOG_FILE   "ioto.log"
 Name of the ioto log file.
#defineIO_LOG_GROUP   "ioto"
 AWS log group name.
#defineIO_LOG_LINGER   5000
 Delay before flushing log events to the cloud.
#defineIO_LOG_MAX_EVENTS   1000
 Max log events to buffer.
#defineIO_LOG_MAX_SIZE   32767
 Max size of log events to buffer.
#defineIO_LOG_STREAM   "agent"
 AWS log stream name.
#defineIO_MAX_URL   256
 Sanity length of a URL.
#defineIO_MESSAGE_SIZE   128 * 1024 * 1024
 Maximum MQTT message size.
#defineIO_PROVISION_FILE   "provision.json5"
 Name of the device provisioning state file.
#defineIO_SAVE_DELAY   5000
 Delay before saving updated shadow state.
#defineIO_SHADOW_FILE   "shadow.json5"
 Name of the persisted AWS shadow state file.
#defineIO_SIGNATURE_FILE   "signature.json5"
 Name of the optional REST API signatures file.
#defineIO_WEB_FILE   "web.json5"
 Name of the web server config file.

Aws

Aws

AWS Support.

Description:
This is suite of AWS helper routines that implement AWS SigV4 signed REST API requests.
API Stability:
Evolving.
See Also:
aws, awsPutFileToS3, awsPutToS3, awsSign
Fields:

int aws (Url *up, cchar *region, cchar *service, cchar *target, cchar *body, ssize bodyLen, cchar *headers, ...)

Invoke an AWS API request.

Parameters:
upUrl object allocated via urlAlloc.
regionAWS Region to target.
serviceAWS Service name. E.g. "s3".
targetAWS Target name. If not supplied, this is deduced from the service name and the "x-amz-target" header.
bodyRequest body data.
bodyLenLength of the request body.
headersFormat string containing HTTP headers. This format string can use printf embedded tokens that will be expanded to form the HTTP headers. The header format is of the form: "Key:Value\n..." with an extra new line at the end.
...Headers arguments.
API Stability:
Evolving.
See Also:
awsPutFileToS3, awsPutToS3, awsSign

int awsPutFileToS3 (cchar *region, cchar *bucket, cchar *key, cchar *filename)

Put a file to AWS S3.

Parameters:
regionAWS Region to target.
bucketAWS S3 bucket name.
keyAWS S3 bucket key (filename). If set to null, the key is set to the filename.
filenameFile name to put to S3.
API Stability:
Evolving.
See Also:
aws, awsPutToS3, awsSign

int awsPutToS3 (cchar *region, cchar *bucket, cchar *key, cchar *data, ssize dataLen)

Put a data block to AWS S3.

Parameters:
regionAWS Region to target.
bucketAWS S3 bucket name.
keyAWS S3 bucket key (filename).
dataData block to write to S3.
dataLenLength of the data block.
API Stability:
Evolving.
See Also:
aws, awsPutFileToS3, awsSign

char * * awsSign (cchar *region, cchar *service, cchar *target, cchar *method, cchar *path, cchar *query, cchar *body, ssize bodyLen, cchar *headers, ...)

Create a set of signed headers to use with AWS SigV4 REST APIs.

Description:
The AWS SDK is big and relatively slow. If you only need a few AWS APIs, you can use the AWS REST APIs and avoid the AWS SDK. This routine processes HTTP request parameters to create a set of signed HTTP headers that can be used with the URL HTTP client.
Parameters:
regionAWS Region to target.
serviceAWS Service name. E.g. "s3".
targetAWS Target name. If not supplied, this is deduced from the service name and the "x-amz-target" header.
methodHTTP method to utilize.
pathURL request path.
queryURL request query.
bodyRequest body data.
bodyLenLength of the request body.
headersFormat string containing HTTP headers. This format string can use printf embedded tokens that will be expanded to form the HTTP headers. The header format is of the form: "Key:Value\n..." with an extra new line at the end.
...Headers arguments.
Returns:
The HTTP headers to use with a URL HTTP client request. Caller must free.
API Stability:
Evolving.
See Also:
aws, awsPutFileToS3, awsPutToS3

Ioto

Ioto

Ioto control structure.

API Stability:
Evolving.
Fields:
char *account Owning manager accountId (provision.json5).
char *api Device cloud API endpoint.
char *apiToken Device cloud API authentication token.
char *app App name.
Json *auth Auth configuraiton.
cchar *awsAccess AWS temp creds.
TimeawsExpires AWS cred expiry.
cchar *awsRegion Default AWS region.
cchar *awsSecret AWS cred secret.
cchar *awsToken AWS cred token.
char *builder Builder API endpoint.
char *cloud Builder cloud ID.
char *cloudType Type of cloud hosting: "hosted", "dedicated".
cchar *cmdAccount Command line override owning manager account for self-claiming.
cchar *cmdCloud Command line override builder cloud for self-claiming.
cchar *cmdConfigDir Command line override directory for config files.
cchar *cmdId Command line override claim ID.
cchar *cmdIotoFile Command line override path for the ioto.json5 config file.
cchar *cmdProduct Command line override Product ID Token.
cchar *cmdProfile Command line override profile.
cchar *cmdStateDir Command line override directory for state files.
cchar *cmdTest Command line override for services.test.
Json *config Configuration.
char *configDir Directory for config files.
booldbService Connected to the cloud over MQTT.
char *endpoint Device cloud API endpoint.
interrors Manufacturing serialization (factory, auto, none).
char *id Claim ID.
char *instance What web request/response headers to trace. EC2 instance.
intiterations Network error count.
boolkeyService Embedded database service.
struct IotoLog *log Configuration max age of the sync log. Cloud Watch Log object.
char *logDir Directory for Ioto log files.
RList *logs Log file ingestion list.
boollogService AWS IAM key generation.
ssizemaxSyncSize Limit of buffered database changes.
boolmqttService Log file ingest to CloudWatch logs.
boolnolocal MQTT service.
boolnosave Do not use local.json.
char *product Product ID Token.
char *profile Run profile. Defaults to ioto.json5:profile (dev, prod).
boolprovisionService Do not save. i.e. run in-memory.
boolregistered Web server.
boolregisterService Cloud provisioning service.
RList *rr Outstanding MQTT request / response list.
char *serializeService Enforce strict signature compliance.
Json *shadow Shadow state.
char *shadowName AWS IoT shadow name.
boolshadowService Device registration service.
char *shadowTopic AWS IoT shadow topic.
boolshortInit AWS IoT core shadows.
Json *signatures Web Rest API signatures.
char *stateDir Directory for state files.
boolstrictSignatures Device has been registered.
TickssyncDelay Delay to flush database changes to the cloud.
TickssyncDue When due to emit sync changes.
REventsyncEvent Schedule synchronization event.
RHash *syncHash Hash of database change records.
FILE *syncLog Sync log file descriptor.
boolsyncService Short initialization for command line commands.
ssizesyncSize Size of buffered database changes.
Json *template Properties for templates.
booltestService Sync device state to AWS.
char *version Your software version number (not Ioto version).
WebHost *webHost Web server host.
boolwebService Test service.
intwebShow Test iterations.

Ioto * * ioAlloc (void )

Allocate the Ioto global object.

API Stability:
Internal.

int ioConfig (Json *config)

User config entry point.

Description:
The ioConfig function is invoked when Ioto has read its configuration into ioto->config and before Ioto initializes services. Users can provide their own ioConfig function and link with the Ioto library. Ioto will then invoke the user's ioConfig for custom configuratoiun.
API Stability:
Evolving.
See Also:
ioStart, ioStop

void ioFlushSync ()

Flush pending changes to the cloud.

Description:
Database changes are buffered before being flushed to the cloud. This forces all pending changes to be sent to the cloud.
API Stability:
Prototype.

void ioFree (void )

Free the Ioto global object.

API Stability:
Internal.

char * * ioGet (cchar *key)

Get a value from the Ioto cloud key/value Store.

Description:
This call retrieves a value from the Ioto cloud key/value store for this device.
Parameters:
keyString key value to assign a value in the store.
Returns:
Value Key's string value. Caller must free.
API Stability:
Evolving.

char * * ioGetConfig (cchar *key, cchar *defaultValue)

Convenience routine to get a value from the Ioto configuration files.

Get a json node value as an allocated string
Description:
This call is a thin wrapper over jsonGet(ioto->config, ...). It returns an allocated string as the result. Use jsonGetRef as a higher performance API if you do not need to retain the queried value.
Parameters:
keyProperty name to search for. This may include ".". For example: "settings.mode".
defaultValueIf the key is not defined, return a copy of the defaultValue. The defaultValue can be NULL in which case the return value will be an allocated empty string.
Returns:
An allocated string copy of the key value or defaultValue if not defined. Caller must free.
API Stability:
Evolving.

double ioGetNum (cchar *key)

Get a numeric value from the Ioto cloud key/value Store.

Description:
This call retrieves a value from the Ioto cloud key/value store for this device.
Parameters:
keyString key value to assign a value in the store.
Returns:
Value Key's numeric value.
API Stability:
Evolving.

cchar * * ioGetShadow (cchar *key, cchar *defaultValue)

Get a value from the shadow state.

Parameters:
keyProperty key value. May contain dots.
defaultValueDefault value to return if the key is not found.
Returns:
Returns and allocated string. Caller must free.
API Stability:
Evolving.

void ioInit (void )

Initialize Ioto.

API Stability:
Evolving.

void ioRestartWeb (void )

Restart the web server.

API Stability:
Evolving.

void ioSaveShadow (void )

Save the shadow state immediately.

API Stability:
Evolving.

void ioSet (cchar *key, cchar *value)

Set a string value in the Ioto cloud key/value Store.

Description:
This call defines a value in the Ioto cloud key/value store for this device.
Parameters:
keyString key value to assign a value in the store.
valueValue to assign to the key.
API Stability:
Evolving.

void ioSetMetric (cchar *metric, double value, cchar *dimensions, int elapsed)

Set a metric value in the Ioto cloud.

Description:
This call defines a metric in the Ioto cloud key/value store for this device.
Parameters:
metricString Metric name to define in the Embedthis/Device namespace.
valueDouble Metric value.
dimensionsJSON array of dimensions as a string. Each element is an object that defines the properties of that dimension. The empty object {} denotes All.
elapsedNumber of seconds to optimize and buffer metric updates before committing to the database.
API Stability:
Evolving.

void ioSetNum (cchar *key, double value)

Set a numeric value in the Ioto cloud key/value Store.

Description:
This call defines a numeric value in the Ioto cloud key/value store for this device.
Parameters:
keyString key value to assign a value in the store.
valueDouble value to assign to the key.
API Stability:
Evolving.

void ioSetShadow (cchar *key, cchar *value, bool save)

Set a key value in the shadow.

Parameters:
keyProperty key value. May contain dots.
valueValue to set.
saveSet to true to persist immediately.
API Stability:
Evolving.

int ioStart (void )

User start entry point.

Description:
The ioStart function is invoked when Ioto is fully initialized and ready to start. Users can provide their own ioStart and ioStop functions and link with the Ioto library. Ioto will then invoke the user's ioStart for custom initialization.
API Stability:
Evolving.
See Also:
ioConfig, ioStop

void ioStop (void )

User stop entry point.

Description:
The ioStop function is invoked when Ioto is shutting down. Users can provide their own ioStart function and link with the Ioto library. Ioto will then invoke the user's ioStop for custom shutdown cleanup.
API Stability:
Evolving.
See Also:
ioConfig, ioStart

void ioSync (bool guarantee)

Sync all items to the cloud.

Description:
This call can be used to force a full sync-up of the local database to the cloud.
Parameters:
guaranteeSet to true to true, peform a reliable sync by waiting for the cloud to send a receipt acknowlegement for each item.
API Stability:
Prototype.

void ioTerm (void )

Terminate Ioto.

API Stability:
Evolving.

char * * mqttRequest (Mqtt *mq, cchar *data, Ticks timeout, cchar *topic, ...)

Issue a MQTT request and wait for a response.

Description:
This call sends a MQTT message to the Ioto service and waits for a response. If the response is not received the call before the timeout expires, the call returns NULL. This call will subscribe for incoming messages on the topic. Use mqttRequestFree if the app does not wish to use mqttRequest again.
Parameters:
mqMQTT connection object.
dataMessage data to send.
timeoutTimeout in milliseconds to wait for a response. If timeout is <= 0, a default timeout of 30 seconds is used.
topicPrintf style topic format string. The supplied topic is appended to 'ioto/device/DEVICE_ID' before sending.
...Topic string arguments.
Returns:
Response message or NULL if the request times out. Caller must free.
API Stability:
Evolving.

void mqttRequestFree (Mqtt *mq, cchar *topic, ...)

Free MQTT subscriptions created by mqttRequest.

Description:
This call is optional and should only be used if you use many different topics with mqttRequest.
Parameters:
mqMQTT connection object.
topicPrintf style topic format string used in prior mqttRequest.
...Topic string arguments.
API Stability:
Evolving.

Typedefs