WebHMI Docs

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Configure AWS IoT Core ===== 
{{ iot:aws:aws_console_no_login.png?direct |}}
The AWS Management Console is a browser-based GUI for Amazon Web Services through which a customer can manage their cloud computing, cloud storage and other resources running on the Amazon Web Services infrastructure. 
==== Log in to your AWS Console ====
To get started, sign up for an account on AWS or log in to your existing account at [[https://console.aws.amazon.com/|AWS Console]].
{{ iot:aws:aws_console.png?direct |}}
Then go to AWS IoT Core.
{{ iot:aws:aws_console_iot_core.png?direct |}}
==== Create a new 'Thing' ====
AWS IoT Core refers to devices that connect to the platform as Things (as a unit of Internet of Things).
There is an AWS IoT Interactive Tutorial to create the first Thing. It is recommended not to skip it for the first time. But to improve the repeatability of the tutorial it would be skipped.
\\ 
\\ 
Go to Manage, Things submenu and let's create a new Thing.
{{ iot:aws:aws_console_iot_create_thing_0.png?direct |}}
Pick the single Thing to be created.
{{ iot:aws:cert:aws_console_iot_create_thing.png?direct |}}
Fill in the required fields, such as Thing's name. Remember that the name can't be changed. But Tags inside that Thing can be edited. 
{{ iot:aws:cert:aws_console_iot_create_thing_1.png?direct |}}
At the moment it would be convenient to create a [[aws-integration#create_a_new_thing_type|Thing Type]] which is a template for new Things. \\ 
\\ 
Select the "one-click certificate creation".
{{ iot:aws:cert:aws_console_iot_create_thing_cert.png?direct |}}
As a result you should see notifications in the top-right corner about successfully created certificates.
{{ iot:aws:cert:aws_console_iot_create_thing_cert_done.png?direct |}}
Download and secure the following files.
Root CA selection and downloading will be shown [[iot:tutorial:aws-integration#create_a_certificates|here]].
==== Create a new Thing Type ====
To effectively create a bunch of 'Things' the best practice is to create a template. Such a template is a 'Thing Type'. It is also a good representation of real-world devices of the same model.
You can also predefine a Tag for Thing, both in template and individual to simplify the search in the fleet of Things and also to understand which real device is bound to particular Thing, e.g. both S/N and location.
==== Create a Certificates ====
At the moment you should have .pem certificate with private and public keys generated and downloaded. Keep them secure.
The last piece of the certificates-puzzle is a Root CA certificate. To publish them or the possibility of its theft is risky due to possible unwanted payments. But that does not apply to Root CA certificate, because it is public already. \\ 
\\ 
 
{{ iot:aws:cert:aws_console_iot_cert_ca.png?direct |aws_console_iot_cert_ca}}
The last step is to activate Thing's certificate in the IoT console, Manage menu entry, Things, select the Thing and go to Security, select linked certificate and click Actions in top right corner and click "Activate".


{{ iot:aws:cert:aws_console_iot_cert_activate.png?direct |}}
The certificate status in the top left corner must change to "ACTIVE".
{{ iot:aws:cert:aws_console_iot_cert_activated.png?direct |}}

==== Create a Policies ====
To establish connection it is policies should be configured.
If there is no policies during Thing creation generated, let's do this manually.
{{ iot:aws:policy:aws_console_iot_create_thing_cert_policy_no_foundh.png?direct |}}
Go to IoT Core Manage, select your Thing, then Secure, Policies. Let's create a new one.
{{ iot:aws:policy:aws_console_iot_create_thing_secure_no_policy.png?direct |}}
Use the following setting to test connection. Wildcard symbol **//*//** represents all of availiable ARNs and subaction such as "iot:Publish", "iot:Subcribe" etc.
{{ iot:aws:policy:aws_console_iot_create_thing_secure_create_policy_best_practise.png?direct |}}
So now it is created.
{{ iot:aws:policy:aws_console_iot_create_thing_secure_create_policy_success.png?direct |}}
So going back to Thing, Certificate, Policies and select the policy that created.
{{ iot:aws:policy:aws_console_iot_create_thing_cert_policy_selected.png?direct |}}
That's how it is should looks like at the final.
{{ iot:aws:policy:aws_console_iot_create_thing_cert_policy_attached.png?direct |}}
==== Interact with AWS IoT Device Shadow ====



This is the current state of AWS Thing's Shadow. It is representation of last reported state of Thing. It is strict formatted, to found out more follow the link: [[https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-document-syntax.html|AWS Shadow format]]

{{ iot:aws:shadow:aws_console_iot_shadow_arn.png?direct |}}
The "Interact" tab is shows to us all of MQTT topics, so that we can see which metric we shound use to interact with and the responses read from. Also here is endpoint, it is MQTT broker address for our connection.
{{ iot:aws:shadow:aws_console_iot_interact_topics.png?direct |}}

==== Test connection via PC client ====

At the moment all settings done. To test it let's configure "MQTT.fx" to work with AWS through TLSv1.2 using .pem certificates as authorization.

Broker Address is the endpoint in the thing interact settings.
According to [[https://docs.aws.amazon.com/iot/latest/developerguide/protocols.html|AWS Developer Guide]] MQTT Broker Port is 8883.


In the end, this leads us to these settings in MQTT.fx to test the connection.
{{ iot:aws:cert:mqttfx_to_aws_settings.png?direct |}}

Click the Apply and try to connect to AWS MQTT Broker. If settings are correct the connection will be established and indicator will be green. 

Let's test shadow change: 
Copy the "...update" MQTT topic from [[http://docs.webhmi.com.ua/_media/wiki:iot:aws:shadow:aws_console_iot_interact_topics.png|Interact]] tab to "Publish" form. 
{{ iot:aws:shadow:aws_console_iot_interact_topics_upd_topic_cr.png?direct |}}
And construct the JSON formatted message to update the shadow. 
<code - MQTT Publish shadow update.json>
{
"state":{
	"reported": {
		    "number": 380567969690,
		    "name": "WebHMI",
		    "status": true
		    }
	}
}
</code>
{{ iot:aws:shadow:mqttfx_to_aws_connected.png?direct |}}
In case of mistake in the JSON format it will be received to "...rejected" topic message:
{{ iot:aws:shadow:mqttfx_subscribe_aws_console_iot_shadow_manual_upd_rejected.png?direct |}}
When everything is configured well, the publish to "...update" topic will lead to "...update/accepted" message with retelling of your payload.
{{ iot:aws:shadow:mqttfx_subscribe_aws_console_iot_shadow_manual_upd_accepted.png?direct |}}
So that, you can notice that Shadow is holds last manual reported state.
{{ iot:aws:shadow:aws_console_iot_shadow_changed.png?direct |}}



==== IoT Core Act/Rules  ====
To take advantage of the data received from the Thing, there is created Rules in Act menu. This is the way to process data, such as head it to analytic or visualisation tools such as QuichSight or Kibana and also run any user actions. 
Now then create a rule, that will store data in the database for the beginning.
The native AWS IoT database is the DynamoDB. To do this you will need create a Table, configure trigger to pull data to it, and apply policy that will allow different AWS service to interact. Let's begin!

Go to AWS IoT Core, Act, Rules. By default, there is no any rules pre-created. 
{{ iot:aws:act:aws_iot_core_thing_act_no_rules.png?direct |}}
Click at "Create a rule", fill in Name. Be careful, it is unchangeable after the creation process. 
{{ iot:aws:act:aws_iot_core_thing_act_create.png?direct |}}

Just fill in the wildcard in the **SELECT** clause and topic in the **FROM**. In our case it is:
<code sql>SELECT * 
FROM '$aws/things/WebHMI_Dnipro_1/shadow/update'</code>

By using wildcard symbol we skip the SQL processing, but we will consider it later. For now, click at "Add action".
{{ iot:aws:act:aws_iot_core_thing_act_iot_republish.png?direct |}}
To test action is working let's just republish the whole JSON payload in the another MQTT topic. Using SQL query it will be possible to filter and even reformat it. So that rule has potential power. 
Fill in a new for testing purposes MQTT topic just to republish the whole message. "''//iot-test//''" for example.
{{ iot:aws:act:aws_iot_core_thing_act_create_republish_topic_name.png?direct |}}
To be able to __publish__ messages it is a role should be applied with a policy that allows it attached. Click at "Create role" and fill in the name for it. It can be renamed, so do not think a lot, try to work out the namespace regular expressions and make the naming process systematic. 
{{ iot:aws:act:aws_iot_core_thing_act_iot_analytics_republish_role.png?direct |}}
After the role created and appropriate policy attached, you will see the "Policy attached" label, which indicates that rule will work with this action and IAM will not prevent action according to this rule, in our case which is republishing message.
{{ iot:aws:act:aws_iot_core_thing_act_iot_analytics_republish_policy_attached.png?direct |}}

Also, to indicate that something went wrong, but the IAM configured well, let's create an //error action//, same republish but in an "//error MQTT branch//", such as ''iot-error''.
{{ iot:aws:act:aws_iot_core_thing_act_iot_analytics_republish_error_rule.png?direct |}}
When those configurations are done, let's test it and pursue that it is working fine.
This time, we will use AWS MQTT Client, which can be found in IoT Core, Test.
To start testing you need to subscribe to all of three topics that you use in your rule. It shound be ''iot-test'', ''iot-error'', and ''$aws/things/WebHMI_Dnipro_1/shadow**/update**'' topics.
{{ iot:aws:act:aws_iot_core_thing_act_iot_analytics_republish_rule_test.png?direct |}}
Test algorithm is to post JSON formatted message to ''.../update'' message and see that it is reposted either to ''iot-test'' or ''iot-error'' topics, which will indicate that rule is applied and actions triggered by rule is not prevented to execute according to IAM. 
{{ iot:aws:act:aws_iot_core_thing_act_republish_test.gif?direct |}}
When to whole message is republished, so now you can configure SQL query filtering. To explicit define the type of the payload variables, you can use CAST function like this. 
<code sql>SELECT cast(state.reported.number as DECIMAL) as digits, 
cast((state.reported.name) as STRING ) as name 
FROM '$aws/things/WebHMI_Dnipro_1/shadow/update'</code>

{{ iot:aws:act:aws_iot_core_thing_act_sql.png?direct |}}
As it is tested, let's get use of the data by guiding them to IoT Analytics. Click one more time at "Add action" button.
{{ iot:aws:act:aws_iot_core_thing_act_iot_analytics.png?direct |}}
Select "Quick create IoT Analytics recouses". Fill in the prefix, which will describe either you rule or the Thing to which that rule is applied. 
{{ iot:aws:act:aws_iot_core_thing_act_iot_analytics_settings.png?direct |}}
By clicking at "Quick create" you will see that it is done so that you are can click "Add action". 
{{ iot:aws:act:aws_iot_core_thing_act_iot_analytics_resoursed_succeed.png?direct |}}





From that time, when the action is added, all the new data that comply with the SQL rule query condition, will be guided to IoT Analytics, so it would be possible to visualise it.
Let's post something to ''...**/update**'' topic just to fill in the sample data into IoT Analytics service.
To do this, go to IoT Core Test //MQTT Client// and publish yet another message, that are valid, which will not go to "error actions" branch of the rule if you setting up the analytics to "Actions" branch and vice versa if "Error Action" branch. 




When it is done, open the IoT Analytics service and interact with data. 
Click "New Analysis button" in the top-left corner.
{{ iot:aws:act:aws_iot_analytics_quicksight_dashboard_new_analysis.png?direct |}}
Then click "New data set".
{{ iot:aws:act:aws_iot_analytics_quicksight_dashboard_new_analysis_new_dataset.png?direct |}}
Pick the "AWS IoT Analytics" new dataset data source.
{{ iot:aws:act:aws_iot_analytics_quicksight_dashboard_new_analysis_new_dataset_source.png?direct |}}
If it is the same with IoT Core region, such as USA, N.Virginia. (US-East-1) which is are free region at the time of writing, you will see that there is one source ready to import. Put the radio button and click "Create data source".
{{ iot:aws:act:aws_iot_analytics_quicksight_dashboard_new_analysis_new_dataset_source_iot_analytics.png?direct |}}

The next step will indicate how much storage is available. For the first time it is near 1 GB SPICE (disk quota) available. Click "Visualize".
{{ iot:aws:act:aws_iot_analytics_quicksight_dashboard_new_analysis_new_dataset_source_iot_analytics_import_finished.png?direct |}}
It is possible to create a various visualisation of your data. Look at the sample dashboard. 
{{ iot:aws:act:aws_iot_analytics_quicksight_dashboard.png?direct |}}

At that point, you can visualize the data from any reporting Thing.
----
DDB
To store the data and be able to query it, you would like to pull in the database. There is AWS DynamoDB integrated for that purpose. Let's create a blank table. 
{{ iot:aws:act:ddb_create.png?direct |}}
It is primary key notion. It is like the main column in the table. The best practise it is SQL-timestamp-formatted-string with timestamp use as primary key.
As we do not have the timestamp in the sample data, the name will be used.
{{ iot:aws:act:ddb:ddb_create_settings.png?direct |}}
This is the blank table. There is no any Items yet. 
{{ iot:aws:act:ddb:ddb_created.png?direct |}}
Let's guide some data to DynamoDB. Go back to the Rule and "Add action" to it, with __"Split message into multiply columns of a DynamoDB table (DynamoDBv2)"__. 
{{ iot:aws:act:ddb:aws_iot_core_thing_act_ddb_rule.png?direct |}}
Fill in the name, select Role and click "Update Role". The green label will indicate that everything is fine and IAM configured well.
{{ iot:aws:act:ddb:aws_iot_core_thing_act_ddb_rule_policy_updated.png?direct |}}
The Rule should look like this.
{{ iot:aws:act:ddb:aws_iot_core_thing_act_ddb.png?direct |}}
This time, you can practice to post message through MQTT.fx or use AWS MQTT Client as you wish. The MQTT.fx client will be considered below.
{{ iot:aws:act:ddb:mqttfx_publish_to_ddb.png?direct |}}
In the final, you will see that you data appear in the your Table in Items tab, if everything is configured well. 
{{ iot:aws:act:ddb:ddb_items_added.png?direct |}}
Otherwise, you will see the ''iot-error'' reported an error with caused reason. That will help you to diagnose the problem and fix it.