AWS IoT Shunya API

AWS IoT core#

AWS IoT core is cloud service provided by Amazon which allows you to communicate and manage IOT edge devices.

Shunya Interfaces implements communication with the AWS cloud using MQTT protocol.

AWS configuration in Shunya#

ConfigDescription
EndpointAWS endpoint url
PortAWS connection port, usually it is 443, 8883 incase 443 is blocked by company proxy
Certificate dirDirectory where we store the AWS certificates, default for shunya is /home/shunya/.cert/aws
Root CA certificate nameAWS provides you with the Root CA certificate. Used for secure communication with AWS.
Client certificateAWS provides certificates that is unique to the each IoT device. Used for secure communication with AWS.
Client KeyAWS provides a key that are unique to the each IoT device. Used for secure communication with AWS.
Client IDUnique Identification of the client, user can put any name that is convenient.

The configurations need to be set manually by the user before using the API's

For example:

A sample JSON snippet should contain

"aws": {
"awsMqttEndpoint": "endpoint-name-here",
"awsMqttPort": 443,
"awsMqttCertDir": "/path/to/certificates/",
"awsMqttRootCert": "name-of-root-CA.crt",
"awsMqttClientCert": "name-of-client-certificate.pub",
"awsMqttPrivKey": "name-of-private-key.pub",
"awsMqttClientId": "unique name given by the user"
},

Commonly configured parameters#

For example:

A typical configuration will look like this

"aws": {
"awsMqttEndpoint": "awer8394haiouery87324.aws",
"awsMqttPort": 8883,
"awsMqttCertDir": "/home/shunya/.cert/aws/",
"awsMqttRootCert": "rootCA.crt",
"awsMqttClientCert": "13987wer.pub",
"awsMqttPrivKey": "123234wer.pub",
"awsMqttClientId": "shunya pi 3"
},

AWS API#

APIDescriptionDetails
newAws()Creates a new AWS InstanceRead More
awsConnectMqtt()Connects to the AWS IoT CloudRead More
awsPublishMqtt()Publishes to the given TopicRead More
awsSubscribeMqtt()Subscribes to the given TopicRead More
awsSetSubCallbackMqtt()Set subscribe callback functionRead More
awsDisconnectMqtt()Subscribes to the given TopicRead More

newAws()#

Description : Creates a new AWS Instance

Parameters

  • name (char *) - Name of the JSON object.

Return-type : awsObj

Returns : awsObj Instance for AWS

Usage :

For example: Lets say your /etc/shunya/config.json JSON file looks like

"awsAccount1": {
"awsMqttEndpoint": "awer8394haiouery87324.aws",
"awsMqttPort": 8883,
"awsMqttCertDir": "/home/shunya/.cert/aws/",
"awsMqttRootCert": "rootCA.crt",
"awsMqttClientCert": "13987wer.pub",
"awsMqttPrivKey": "123234wer.pub",
"awsMqttClientId": "shunya pi 3"
},

So the usage of the API's will be

awsObj awsAccount1 = newAws("awsAccount1");

awsConnectMqtt()#

Description : Connects to the AWS IoT Cloud.

Parameters

  • *obj(awsObj) - Pointer to the AWS Instance.

Return-type : int32_t

Returns : AWS Status Code on ERROR or SUCCESS

Usage :

/* Load settings and then connect to AWS */
awsObj awsAccount1 = newAws("awsAccount1");
awsConnectMqtt(&awsAccount1);

awsPublishMqtt()#

Description : Publishes to the given Topic

Parameters

  • *obj(awsObj) - Pointer to the AWS Instance.
  • topic (char *) - MQTT Topic to publish.
  • msg (char *) - Message that needs to be published.

Return-type : int32_t

Returns : AWS Status Code on ERROR or SUCCESS

Usage :

/* Load settings and then connect to AWS */
awsObj awsAccount1 = newAws("awsAccount1");
awsConnectMqtt(&awsAccount1);
awsPublishMqtt(&awsAccount1, "topic", "Send this message");

awsSubscribeMqtt()#

Description: Subscribes to the given Topic.

Parameters

  • *obj(awsObj) - Pointer to the AWS Instance.
  • topic (char *) - MQTT Topic to subscribe.

Return-type : int32_t

Returns : AWS Status Code on ERROR or SUCCESS

Usage :

/* Load settings and then connect to AWS */
awsObj awsAccount1 = newAws("awsAccount1");
awsConnectMqtt(&awsAccount1);
awsSubscribeMqtt(&awsAccount1, "topic");

awsSetSubCallbackMqtt()#

Description: Set the subscribe callback function that executes the when the topic subscribed gets a message.

The Callback function arguments need to be in the specified format,

void callback(int topicLen, char *topic, int msgLen, char *message)

This format is used to pass the message received to the callback function.

Parameters

  • *obj(awsObj) - Pointer to the AWS Instance.
  • callback (void *) - A callback function that will get called when the subscribed topic gets a message

Return-type : int32_t

Returns : AWS Status Code on ERROR or SUCCESS

Usage :

/* Load settings and then connect to AWS */
awsObj awsAccount1 = newAws("awsAccount1");
void callback(int topicLen, char *topic, int msgLen, char *message)
{
printf("Received Message is: %s", message);
}
awsSetSubCallbackMqtt(&awsAccount1, callback);

awsDisconnectMqtt()#

Description: Disconnects the AWS MQTT Broker.

Parameters:

  • *obj(awsObj) - Pointer to the AWS Instance.

Return-type : void

Usage :

awsDisconnectMqtt(&awsAccount1);