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.
intioConfig(Json *config)
 User config entry point.
cchar*ioGetShadow(cchar *key, cchar *defaultValue)
 Get a value from the shadow state.
voidioInit(cchar *profile)
 Initialize Ioto.
voidioSaveShadow(void)
 Save the shadow state immediately.
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.
voidioTerm(void)
 Terminate Ioto.
ssizewebWriteItem(Web *web, const DbItem *item)
 Write a database item as part of a web response.
ssizewebWriteItems(Web *web, const DbGrid *items)
 Write a grid of database items as part of a web response.

Typedefs

Defines

#defineIA_CONFIG_FILE   "config/config.json5"
 Name of the primary control config file.
#defineIA_DEVICE_FILE   "config/device.json5"
 Name of the device identification config file.
#defineIA_LOCAL_FILE   "config/local.json5"
 Development overrides.
#defineIA_LOG_FILE   "ioto.log"
 Name of the ioto log file.
#defineIA_LOG_GROUP   "ioto"
 AWS log group name.
#defineIA_LOG_LINGER   5000
 Delay before flushing log events to the cloud.
#defineIA_LOG_MAX_EVENTS   1000
 Max log events to buffer.
#defineIA_LOG_MAX_SIZE   32767
 Max size of log events to buffer.
#defineIA_LOG_STREAM   "agent"
 AWS log stream name.
#defineIA_MAX_URL   256
 Sanity length of a URL.
#defineIA_MESSAGE_SIZE   128 * 1024 * 1024
 Maximum MQTT message size.
#defineIA_PROVISION_FILE   "config/provision.json5"
 Name of the device provisioning config file.
#defineIA_SAVE_DELAY   5000
 Delay before saving updated shadow state.
#defineIA_SHADOW_FILE   "config/shadow.json5"
 Name of the persisted AWS shadow state file.
#defineIA_SIGNATURES_FILE   "config/signatures.json5"
 Name of the primary control config file.
#defineIA_WEB_FILE   "config/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:
cchar *api Device cloud API endpoint.
cchar *apiToken Device cloud API authentication token.
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.
cchar *builder Builder API endpoint.
cchar *claimId Claim ID.
boolcloudService Embedded database service.
Json *config Configuration.
Db *db Structured state database.
RBuf *dbChanges Buffer of database change records.
cchar *deviceId Device ID.
TicksfirstSyncChange When the first database state change happend.
char *instance Enforce strict signature compliance. EC2 instance.
boolkeyService Manufacturing serialization.
cchar *loadPath Database file to load.
struct IotoLog *log Cloud Watch Log object.
RList *logs Log file ingestion list.
boollogService AWS IAM key generation.
Mqtt *mqtt Mqtt object.
boolmqttService Log file ingest to CloudWatch logs.
char *profile Run profile. Defaults to "prod".
boolprovisionService MQTT service.
boolregistered Web server.
boolregisterService Cloud provisioning service.
boolserializeService AWS IoT core service.
Json *shadow Shadow state.
cchar *shadowName AWS IoT shadow name.
boolshadowService Device registration service.
char *shadowTopic AWS IoT shadow topic.
Json *signatures Web Rest API signatures.
boolstrictSignatures Device has been registered.
TickssyncDelay Delay to flush database changes to the cloud.
REventsyncEvent Schedule synchronization event.
ssizesyncLimit Limit of buffered database changes.
boolsyncService AWS IoT core shadows.
cchar *syncToken Authentication token when sending database changes to the cloud.
Json *template Properties for templates.
cchar *thingName AWS IoT thing name.
WebHost *webHost Web server host.
boolwebService Sync device state to AWS.

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

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.
API Stability:
Evolving.
See Also:

void ioInit (cchar *profile)

Initialize Ioto.

Parameters:
profileConfiguration profile. Defaults to "prod".
API Stability:
Evolving.
See Also:

void ioSaveShadow (void )

Save the shadow state immediately.

API Stability:
Evolving.
See Also:

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.
See Also:

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 ioTerm (void )

Terminate Ioto.

API Stability:
Evolving.
See Also:

ssize webWriteItem (Web *web, const DbItem *item)

Write a database item as part of a web response.

Description:
This routine serialize a database item into JSON and write it as a response.
Parameters:
webWeb object.
itemDatabase item.
Returns:
The number of bytes written.
API Stability:
Evolving.
See Also:

ssize webWriteItems (Web *web, const DbGrid *items)

Write a grid of database items as part of a web response.

Description:
This routine serializes a database grid into JSON and write it as a response.
Parameters:
webWeb object.
itemsGrid of database items.
Returns:
The number of bytes written.
API Stability:
Evolving.
See Also:

Typedefs