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:

• Crypt
• Database
• Embedded Web Server
• JSON parser
• MQTT client
• Safe Runtime
• Url HTTP Client

Extensions

Aws	AWS Support.
Ioto	Ioto control structure.

Functions

int	aws(Url *up, cchar *region, cchar *service, cchar *target, cchar *body, ssize bodyLen, cchar *headers, ...)
	Invoke an AWS API request.
int	awsPutFileToS3(cchar *region, cchar *bucket, cchar *key, cchar *filename)
	Put a file to AWS S3.
int	awsPutToS3(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.
int	ioConfig(Json *config)
	User config entry point.
void	ioConnectSync(void)
	Subscribe for DB sync messages after connecting to the cloud.
void	ioFlushSync(bool force)
	Flush pending changes to the cloud.
void	ioFree(void)
	Free the Ioto global object.
char *	ioGet(cchar *key)
	Get a value from the Ioto cloud key/value Store.
cchar *	ioGetConfig(cchar *key, cchar *defaultValue)
	Convenience routine to get a value from the Ioto configuration files.
int	ioGetConfigInt(cchar *key, int defaultValue)
	Convenience routine to get an integer value from the Ioto configuration files.
double	ioGetMetric(cchar *metric, cchar *dimensions, cchar *statistic, int period)
	Get a metric value in the Ioto cloud.
double	ioGetNum(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.
void	ioInit(void)
	Initialize Ioto.
void	ioRestartWeb(void)
	Restart the web server.
int	ioRun(void)
	Start Ioto services.
void	ioSaveShadow(void)
	Save the shadow state immediately.
void	ioSet(cchar *key, cchar *value)
	Set a string value in the Ioto cloud key/value Store.
void	ioSetMetric(cchar *metric, double value, cchar *dimensions, int elapsed)
	Set a metric value in the Ioto cloud.
void	ioSetNum(cchar *key, double value)
	Set a numeric value in the Ioto cloud key/value Store.
void	ioSetShadow(cchar *key, cchar *value, bool save)
	Set a key value in the shadow.
int	ioStart(void)
	User start entry point.
int	ioStartRuntime(int verbose)
	Initialize the Ioto runtime.
void	ioStop(void)
	User stop entry point.
void	ioSync(bool guarantee)
	Sync all items to the cloud.
void	ioTerm(void)
	Terminate Ioto.
char *	mqttRequest(Mqtt *mq, cchar *data, Ticks timeout, cchar *topic, ...)
	Issue a MQTT request and wait for a response.
void	mqttRequestFree(Mqtt *mq, cchar *topic, ...)
	Free MQTT subscriptions created by mqttRequest.

Typedefs

Defines

#define	IO_CERTIFICATE   "ioto.crt"
	Name of the AWS thing certificate file.
#define	IO_CONFIG_FILE   "ioto.json5"
	Primary Ioto config file.
#define	IO_DEVICE_FILE   "device.json5"
	Name of the device identification config file.
#define	IO_KEY   "ioto.key"
	Name of the AWS thing key file.
#define	IO_LOCAL_FILE   "local.json5"
	Development overrides.
#define	IO_LOG_FILE   "ioto.log"
	Name of the ioto log file.
#define	IO_LOG_GROUP   "ioto"
	AWS log group name.
#define	IO_LOG_LINGER   5000
	Delay before flushing log events to the cloud.
#define	IO_LOG_MAX_EVENTS   1000
	Max log events to buffer.
#define	IO_LOG_MAX_SIZE   32767
	Max size of log events to buffer.
#define	IO_LOG_STREAM   "agent"
	AWS log stream name.
#define	IO_MAX_URL   256
	Sanity length of a URL.
#define	IO_MESSAGE_SIZE   128 * 1024 * 1024
	Maximum AWS MQTT message size (reduced).
#define	IO_PROVISION_FILE   "provision.json5"
	Name of the device provisioning state file.
#define	IO_SAVE_DELAY   5000
	Delay before saving updated shadow state.
#define	IO_SHADOW_FILE   "shadow.json5"
	Name of the persisted AWS shadow state file.
#define	IO_SIGNATURE_FILE   "signature.json5"
	Name of the optional REST API signatures file.
#define	IO_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:

up	Url object allocated via urlAlloc.
region	AWS Region to target.
service	AWS Service name. E.g. "s3".
target	AWS Target name. If not supplied, this is deduced from the service name and the "x-amz-target" header.
body	Request body data.
bodyLen	Length of the request body.
headers	Format 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:

region	AWS Region to target.
bucket	AWS S3 bucket name.
key	AWS S3 bucket key (filename). If set to null, the key is set to the filename.
filename	File 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:

region	AWS Region to target.
bucket	AWS S3 bucket name.
key	AWS S3 bucket key (filename).
data	Data block to write to S3.
dataLen	Length 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:

region	AWS Region to target.
service	AWS Service name. E.g. "s3".
target	AWS Target name. If not supplied, this is deduced from the service name and the "x-amz-target" header.
method	HTTP method to utilize.
path	URL request path.
query	URL request query.
body	Request body data.
bodyLen	Length of the request body.
headers	Format 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.
char *		awsAccess	AWS temp creds.
Time		awsExpires	AWS cred expiry.
char *		awsRegion	Default AWS region.
char *		awsSecret	AWS cred secret.
char *		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.
char *		cmdConfigDir	Command line override directory for config files.
int		cmdCount	Command line reset.
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.
cchar *		cmdWebShow	Command line override for web request/response trace.
Json *		config	Configuration.
char *		configDir	Directory for config files.
bool		connected	Test iterations.
bool		dbService	Ioto fully initialized and ready for requests (may not be connected to the cloud).
char *		endpoint	Device cloud API endpoint.
char *		id	Claim ID.
char *		instance	Manufacturing serialization (factory, auto, none). EC2 instance.
bool		keyService	Embedded database service.
struct IotoLog *		log	Cloud Watch Log object.
char *		logDir	Directory for Ioto log files.
RList *		logs	Log file ingestion list.
bool		logService	AWS IAM key generation.
ssize		maxSyncSize	Limit of buffered database changes.
bool		mqttService	Log file ingest to CloudWatch logs.
bool		nosave	MQTT service.
char *		product	Product ID Token.
char *		profile	Run profile. Defaults to ioto.json5:profile (dev, prod).
bool		provisioned	Do not save. i.e. run in-memory.
bool		provisionService	Provisioned with the cloud.
bool		ready	Connected to the cloud over MQTT.
bool		registered	Web server.
bool		registerService	Cloud provisioning service.
REvent		scheduledConnect	Schedule connection event.
char *		serializeService	Enforce strict signature compliance.
Json *		shadow	Shadow state.
char *		shadowName	AWS IoT shadow name.
bool		shadowService	Device registration service.
char *		shadowTopic	AWS IoT shadow topic.
Json *		signatures	Web Rest API signatures.
char *		stateDir	Directory for state files.
bool		strictSignatures	Device has been registered.
Ticks		syncDue	When due to emit sync changes.
REvent		syncEvent	Schedule synchronization event.
RHash *		syncHash	Hash of database change records.
FILE *		syncLog	Sync log file descriptor.
bool		syncService	AWS IoT core shadows.
ssize		syncSize	Size of buffered database changes.
Json *		template	Properties for templates.
bool		testService	Sync device state to AWS.
bool		updateService	Test service.
char *		version	Your software version number (not Ioto version).
WebHost *		webHost	Web server host.
bool		webService	Update service.

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

Subscribe for DB sync messages after connecting to the cloud.

API Stability:

Internal.

void ioFlushSync (bool force)

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.

Parameters:

force

Set to true to flush items that are not yet due to be sync'd.

API Stability:

Evolving.

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:

key	String key value to assign a value in the store.

Returns:

Value Key's string value. Caller must free.

API Stability:

Evolving.

cchar * * 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, ...).

Parameters:

key	Property name to search for. This may include ".". For example: "settings.mode".
defaultValue	If 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 string reference into the config store or defaultValue if not defined. Caller must not free.

API Stability:

Evolving.

int ioGetConfigInt (cchar *key, int defaultValue)

Convenience routine to get an integer value from the Ioto configuration files.

Parameters:

key	Property name to search for. This may include ".". For example: "settings.mode".
defaultValue	If the key is not defined, return the defaultValue.

Returns:

The integer value from the config store or defaultValue if not defined.

API Stability:

Evolving.

double ioGetMetric (cchar *metric, cchar *dimensions, cchar *statistic, int period)

Get a metric value in the Ioto cloud.

Description:

This call retrieves a metric in the Ioto cloud for this device.

Parameters:

metric	String Metric name to define in the Embedthis/Device namespace.
dimensions	JSON array of dimensions as a string. Each element is an object that defines the properties of that dimension. The empty object {} denotes All.
statistic	Set to avg, min, max, count or current.
period	Number of seconds for the statistic period.

Returns:

The metric value or NAN if it cannot be found.

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:

key	String 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:

key	Property key value. May contain dots.
defaultValue	Default 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.

int ioRun (void )

Start Ioto services.

Description:

This routine blocks and services Ioto requests until commanded to exit via rStop().

Returns:

Zero if successful, otherwise a negative error code.

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:

key	String key value to assign a value in the store.
value	Value 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 for this device.

Parameters:

metric	String Metric name to define in the Embedthis/Device namespace.
value	Double Metric value.
dimensions	JSON array of dimensions as a string. Each element is an object that defines the properties of that dimension. The empty object {} denotes All.
elapsed	Number 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:

key	String key value to assign a value in the store.
value	Double 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:

key	Property key value. May contain dots.
value	Value to set.
save	Set 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

int ioStartRuntime (int verbose)

Initialize the Ioto runtime.

Parameters:

verbose

Set to 1 to enable verbose output. Set to 2 for debug output.

Returns:

Zero if successful, otherwise a negative error code.

API Stability:

Evolving.

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:

guarantee

Set to true to true, peform a reliable sync by waiting for the cloud to send a receipt acknowlegement for each item.

API Stability:

Evolving.

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:

mq	MQTT connection object.
data	Message data to send.
timeout	Timeout in milliseconds to wait for a response. If timeout is <= 0, a default timeout of 30 seconds is used.
topic	Printf 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:

mq	MQTT connection object.
topic	Printf style topic format string used in prior mqttRequest.
...	Topic string arguments.

API Stability:

Evolving.

Typedefs