Changes

Template:AWSinstructions (view source)

Revision as of 13:10, 15 September 2023

5,028 bytes added ,  13:10, 15 September 2023
no edit summary
Line 1: Line 1:  +
<!--For quick start guide how to use Teltonika Telematics devices with AWS IoT Core can be downloaded [https://wiki.teltonika-gps.com/images/c/c5/MQTT_AWS_IoT_Custom_Configuration_Guide_V1.pdf here]
 +
Getting Started Guide for AWS IoT can be downloaded [https://wiki.teltonika-gps.com/images/c/cf/AWS_GSG_v1.4.pdf here]-->
 +
 +
== '''Document Information''' ==
 +
=== '''Glossary''' ===
 +
* Wiki – Teltonika IoT knowledge base - https://wiki.teltonika-iot-group.com/.
 +
* FOTA – Firmware Over The Air.
 +
* Configurator – Tool to configure Teltonika Telematics devices.
 +
* Crowd support forum – knowledge base dedicated for Troubleshooting.
 +
 +
 +
'''For firmware supporting MQTT please contact your sales manager or contact directly via Teltonika Helpdesk.'''
 +
 +
== '''Other software required to develop and debug applications for the device''' ==
 +
 +
For debugging situations, device internal logs can be downloaded OTA by using our [https://fm.teltonika.lt/ FotaWEB] platform or by using Teltonika Configurator.
 
== '''Setup your AWS account and Permissions''' ==
 
== '''Setup your AWS account and Permissions''' ==
 
Refer to the online AWS documentation at Set up your AWS Account.  Follow the steps outlined in the sections below to create your account and a user and get started:<br>
 
Refer to the online AWS documentation at Set up your AWS Account.  Follow the steps outlined in the sections below to create your account and a user and get started:<br>
   −
* [https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html#aws-registration Sign up for an AWS account and]  
+
* [https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html#aws-registration Sign up for an AWS account]  
 
* [https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html#create-iam-user Create a user and grant permissions]
 
* [https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html#create-iam-user Create a user and grant permissions]
 
* [https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html#iot-console-signin Open the AWS IoT console]
 
* [https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html#iot-console-signin Open the AWS IoT console]
 
<br>
 
<br>
−
NOTE – The examples in this document are intended only for dev environments. All devices in your production fleet must have credentials with privileges that authorize only intended actions on specific resources. The specific permission policies can vary for your use case. Identify the permission policies that best meet your business and security requirements. For more information, refer to [https://docs.aws.amazon.com/iot/latest/developerguide/example-iot-policies.html Example policies] and [https://docs.aws.amazon.com/iot/latest/developerguide/security-best-practices.html Security Best practices].
+
Pay special attention to the Notes.
 
<br>
 
<br>
 +
 
== '''Create Resources in AWS IoT''' ==
 
== '''Create Resources in AWS IoT''' ==
 
Refer to the online AWS documentation at Create AWS IoT Resources.  Follow the steps outlined in these sections to provision resources for your device:
 
Refer to the online AWS documentation at Create AWS IoT Resources.  Follow the steps outlined in these sections to provision resources for your device:
Line 14: Line 31:  
* [https://docs.aws.amazon.com/iot/latest/developerguide/create-iot-resources.html#create-aws-thing Create a thing object]
 
* [https://docs.aws.amazon.com/iot/latest/developerguide/create-iot-resources.html#create-aws-thing Create a thing object]
 
<br>
 
<br>
−
NOTE – The examples in this document are intended only for dev environments. All devices in your production fleet must have credentials with privileges that authorize only intended actions on specific resources. The specific permission policies can vary for your use case. Identify the permission policies that best meet your business and security requirements. For more information, refer to [https://docs.aws.amazon.com/iot/latest/developerguide/example-iot-policies.html Example policies] and [https://docs.aws.amazon.com/iot/latest/developerguide/security-best-practices.html Security Best practices].
+
Pay special attention to the Notes.
 
<br>
 
<br>
−
== '''Provision the Device with credentials''' ==
+
== '''Provide Device with credentials''' ==
 
Whole device, AWS IoT and testing information can be downloaded in PDF format [https://wiki.teltonika-gps.com/images/c/c5/MQTT_AWS_IoT_Custom_Configuration_Guide_V1.pdf here.]
 
Whole device, AWS IoT and testing information can be downloaded in PDF format [https://wiki.teltonika-gps.com/images/c/c5/MQTT_AWS_IoT_Custom_Configuration_Guide_V1.pdf here.]
−
=== ''AWS IoT Core Configuration'' ===
+
<br><br>NOTE: MQTT will not work without uploaded TLS certificates.
−
==== ''Setting up AWS IoT Core'' ====
+
=== '''AWS IoT Core Configuration''' ===
−
When logged in the AWS console, click on Services on the top left hand side screen, to access IoT core.
+
==== '''Setting up AWS IoT Core''' ====
−
<br>
+
 
−
[[File:AWS_MQTT_1.png|frameless|alt=|center|934x425px]]
+
 
 +
<br>When logged in the AWS console, click on Services on the top left hand side screen, to access IoT core.
 +
 
 +
 
 +
[[File:Accessing_IoT_Core.jpg|934x425px]]
 
<div style="text-align: center;">Figure 1. Accessing AWS IoT core from AWS console</div>
 
<div style="text-align: center;">Figure 1. Accessing AWS IoT core from AWS console</div>
 +
NOTE: If you can't see "Services" in the top left, click on "My account" in the top right and "AWS Management Console"
 +
 +
 +
Select Manage, Security, Policies (Manage > Security > Policies) and press Create policy or Create buttons.
 +
[[File:Accessing_policy_creation.png|934x425px]]
 +
<div style="text-align: center;">Figure 2. Accessing policy creation</div>
 +
 +
 +
In the Create Policy window, enter Policy name. In the Policy document tab for Policy Action (1) select “*” and for Policy resource (2) enter “*” and press create.
 +
[[File:Creating_policy.png|934x425px]]
 +
<div style="text-align: center;">Figure 3. Creating a policy</div>
 +
   −
After accessing AWS IoT core, select Manage on the sidebar on the left side, then select Things (Manage- >Things). And click on Create things.
+
Now, that you have created a policy, select Manage on the sidebar on the left side, then select All devices, Things (Manage>All devices>Things). And click on Create things.  
 
<br>
 
<br>
−
[[File:AWS_MQTT_2.png|frameless|alt=|center|934x425px]]
+
[[File:Go_to_create_things.bmp|934x425px]]
−
<div style="text-align: center;">Figure 2. Accessing Things</div>
+
<div style="text-align: center;">Figure 4. Accessing Things</div>
−
Afterwards for select Create single thing and click Next.
+
 
 +
 
 +
Afterwards select Create single thing and click Next.
 
<br>
 
<br>
−
[[File:AWS_MQTT_3.png|frameless|alt=|center|934x425px]]
+
[[File:Creating_thing.jpg|934x425px]]
−
<div style="text-align: center;">Figure 3. Creating single thing</div>
+
<div style="text-align: center;">Figure 5. Creating single thing</div>
−
After creating single thing, enter Thing’s name and in the Device Shadow tab select Unnamed shadow (classic). Then click Next.
+
 
−
[[File:AWS_MQTT_4.png|frameless|alt=|center|934x425px]]
+
 
−
<div style="text-align: center;">Figure 4. Specifying thing properties</div>
+
After creating a single thing, enter Thing’s name and in the Device Shadow tab select Unnamed shadow (classic). Then click Next.
−
Then when selecting Device certificate, select Auto-generate a new certificate and click Next
+
[[File:Thing's_properties.jpg|934x425px]]
−
[[File:AWS_MQTT_5.png|frameless|alt=|center|934x425px]]
+
<div style="text-align: center;">Figure 6. Thing's properties</div>
−
<div style="text-align: center;">Figure 5. Selecting Certificate</div>
+
 
−
After this select Create policy to create it and attach it to Certificate. In the Create Policy window, enter Policy name. In the Policy document (1) tab for Policy Action (2) select * and for Policy resource enter * .
+
 
−
[[File:AWS_MQTT_6.png|frameless|alt=|center|934x425px]]
+
Then when selecting Device certificate, select Auto-generate a new certificate and click Next.
−
<div style="text-align: center;">Figure 6. Creating policy for Certificate</div>
+
[[File:Certificate_configuration.jpg|934x425px]]
−
After creating policy, return to Certificate tab (Seperate tab after pressing Create policy should‘ve popped out). Then select the created policy to attach it to the certificate and thing. After that click Create thing
+
<div style="text-align: center;">Figure 7. Certificate configuration</div>
−
[[File:AWS_MQTT_7.png|frameless|alt=|center|934x425px]]
+
 
−
<div style="text-align: center;">Figure 7. Attaching created certificate and creating thing</div>
+
 
−
Then window with Certificate files and key files download options should pop out. It‘s recommended to download all files, because later some of them will not be available for download. The files that are required for usage with FMX devices are: Device certificate (1), private key(2), and Amazon Root CA 1 file(3), but it‘s recommended to download them all and store them in secured place.
+
Now, select the policy you have created before to attach it to the certificate and thing. After that click Create thing.
−
[[File:AWS_MQTT_8.png|frameless|alt=|center|934x425px]]
+
[[File:Attaching_policy_to_certificate.jpg|934x425px]]
−
<div style="text-align: center;">Figure 8. Certificate files download window</div>
+
<div style="text-align: center;">Figure 8. Attaching policy to certificate</div>
 +
 
 +
 
 +
Then window with Certificate files and key files download options should pop out. It‘s recommended to download all files, because later some of them will not be available for download. The files that are required for usage with FMX devices are: Device certificate (1), private key(2), and Amazon Root CA 1 file(3), but it‘s recommended to download them all and store them in secured place.<br>
 +
[[File:Certificate_and_key_download.jpg|934x425px]]
 +
<div style="text-align: center;">Figure 9. Certificate and key download</div>
 +
 
   −
==== ''Finding device data endpoint (server domain)'' ====
+
==== '''Finding device data endpoint (server domain)''' ====
−
To receive server domain (in AWS endpoint) click on the side bar on the left Settings.
+
To receive server domain (in AWS endpoint) click on the side bar on the left Settings (AWS IoT->Settings).  
 
Or click on the side bar on left side Things, select the created thing, after it click Interact->View Settings. Whole path - (Things->*YourThingName*->Interact->ViewSettings). Page containing endpoint will open. Copy the whole endpoint address.
 
Or click on the side bar on left side Things, select the created thing, after it click Interact->View Settings. Whole path - (Things->*YourThingName*->Interact->ViewSettings). Page containing endpoint will open. Copy the whole endpoint address.
−
Port for accessing this endpoint is 8883.
+
Port for accessing this endpoint is 8883.<br>
−
[[File:AWS_MQTT_9.png|frameless|alt=|center|934x425px]]
+
[[File:Device_data_endpoint.jpg|934x425px]]
−
<div style="text-align: center;">Figure 9. Device data endpoint</div>
+
<div style="text-align: center;">Figure 10. Device data endpoint</div>
 +
 
 +
=== '''Merging certificates into a single file (FW Ver. 03.28.03.Rev.311)''' ===
 +
Merger download: [[Media:Crt_MRGs.zip]]
 +
NOTE: for FW Ver. 03.28.03.Rev.311 it is possible to upload a single merged file instead of 3 separate files.
 +
First, double click certificate merger to execute the program.
 +
[[File:Certificate_merger.png|934x425px]]
 +
<div style="text-align: center;">Figure 11. Certificate merger</div>
 +
 
 +
 
 +
Then, a screen will pop out asking to select a certificate. Go to the folder with your certificate, private key and root certificate. Select the certificate.
 +
[[File:Selecting_certificate.png|934x425px]]
 +
<div style="text-align: center;">Figure 12. Selecting certificate</div>
 +
 
 +
 
 +
Another screen will pop out asking to select private key, so select private key.
 +
[[File:Selecting_private_key.png|934x425px]]
 +
<div style="text-align: center;">Figure 13. Selecting private key</div>
   −
=== ''Configuring the device'' ===
     −
==== ''Security and certificates'' ====
+
Last screen will ask you to select the root certificate.<br>
−
Find Certificate file ending with extension pem.crt Private key file and AmazoonRootCA1 file (no need to change filenames). These file should have been downloaded when creating Thing in AWS IoT Core.
+
[[File:Selecting_root_certificate.png|934x425px]]
−
[[File:AWS_MQTT_10.png|frameless|alt=|center|934x425px]]
+
<div style="text-align: center;">Figure 14. Selecting root certificate</div>
−
<div style="text-align: center;">Figure 10. Certificate files</div>
+
 
 +
 
 +
After selecting the root certificate your files will be merged and a new “Merged” folder will appear inside your certificate folder. Inside it will be the merged_cert.pem.
 +
[[File:Merged_folder.png|934x425px]]
 +
<div style="text-align: center;">Figure 15. Merged folder</div>
 +
[[File:Merged_certificate.png|934x425px]]
 +
<div style="text-align: center;">Figure 16. Merged file</div>
 +
 
 +
=== '''Configuring the device''' ===
 +
==== '''Security and certificates''' ====
 +
<br>
 +
===== '''Using certificate, private key and root certificate. (Via Cable)''' =====
 +
Find Certificate file ending with extension pem.crt (ending may be just .pem) Private key file and AmazoonRootCA1 file (no need to change filenames). These files should have been downloaded when creating Thing in AWS IoT Core.<br>
 +
[[File:Certificate_and_key_download.jpg|934x425px]]
 +
<div style="text-align: center;">Figure 17. Certificate, private key and root certificate</div>
 +
 
 +
Upload the mentioned files in the Security tab in the Teltonika Configurator.<br>
 +
[[File:Uploading_certificates_to_configurator.png|934x425px]]
 +
<div style="text-align: center;">Figure 18. Uploading certificates and keys</div>
 +
 
 +
 
 +
After uploading certificates, go to System tab and in Data protocol section select - Codec JSON.<br>
 +
[[File:Choosing_data_protocol.jpg|934x425px]]
 +
<div style="text-align: center;">Figure 19. Choosing data protocol</div>
 +
 
 +
==== '''Using FW Ver. 03.28.03.Rev.311 and merged_cert.pem file. (Via FOTA WEB)''' ====
 +
 
 +
NOTE: uploading merged certificate file is only possible using FW Ver. 03.28.03.Rev.311.
 +
<br>
 +
Open FOTA WEB and press devices side bar. Then select a device you want to upload merged certificate to and press create task.
 +
[[File:FOTA_WEB_Devices.png|934x425px]]
 +
<div style="text-align: center;">Figure 20. Selecting device</div>
 +
 
 +
 
 +
A “Create task” window will pop up. Select task type “Transfer user TLS certificate”. Press “Upload new file” to upload your merged certificate. If you already have uploaded the merged certificate skip the next step.<br>
 +
[[File:Creating_task.png|934x425px]]
 +
<div style="text-align: center;">Figure 21. Creating task</div>
 +
 
 +
 
 +
“Upload file” window will pop up. Change file type to Certificate, choose your company, press select files, find the merged file you created in step 3 and double tap. Click “Upload” button. Another window may appear with uploaded file information, simply click “Close”.<br>
 +
[[File:Upload_merged_file.png|934x425px]]
 +
<div style="text-align: center;">Figure 22. Uploading merged file</div>
 +
 
 +
 
 +
Now you should be back in “Create task” window. Select the certificate you have just created and press “Create”.<br>
 +
[[File:Selecting_task_certificate.png|934x425px]]
 +
<div style="text-align: center;">Figure 23. Selecting certificate</div>
 +
 
 +
 
 +
Your task has been created and is now pending.
 +
[[File:Pending_task.png|934x425px]]
 +
<div style="text-align: center;">Figure 24. Pending task</div>
 +
 
 +
To have the task completed send an SMS command to your device:
 +
<br><br><code><SMS login><space><SMS password><space><web_connect></code>
 +
<br><br>If you have no login or password your message should look like this:
 +
<br><br><code>„  web_connect“</code>
 +
 
 +
This is how the merged certificate should look in configurator after upload:<br>
 +
[[File:Uploaded_and_merger_certificate.png|934x425px]]
 +
<div style="text-align: center;">Figure 25. Uploaded merged certificate</div>
 +
 
   −
Upload the mentioned files in the Security tab in the Teltonika Configurator.
  −
[[File:AWS_MQTT_11.png|frameless|alt=|center|934x425px]]
  −
<div style="text-align: center;">Figure 11. Uploading certificates</div>
   
After uploading certificates, go to System tab and in Data protocol section select - Codec JSON.
 
After uploading certificates, go to System tab and in Data protocol section select - Codec JSON.
 +
[[File:Choosing_data_protocol.jpg|934x425px]]
 +
<div style="text-align: center;">Figure 26. Choosing data protocol</div>
   −
[[File:AWS_MQTT_12.png|frameless|alt=|center|934x425px]]
+
==== '''Device GPRS configuration for AWS IoT Custom MQTT settings''' ====
−
<div style="text-align: center;">Figure 12. Selecting Data Protocol</div>
  −
 
  −
==== ''Device GPRS configuration for AWS IoT Custom MQTT settings'' ====
   
In the GPRS tab, under Server Settings select:  
 
In the GPRS tab, under Server Settings select:  
 
# Domain – Endpoint from the AWS, Port: 8883  
 
# Domain – Endpoint from the AWS, Port: 8883  
 
# Protocol – MQTT  
 
# Protocol – MQTT  
 
# TLS Encryption – TLS/DTLS
 
# TLS Encryption – TLS/DTLS
−
<br>
+
<br><br>
 
In the MQTT Settings section select:
 
In the MQTT Settings section select:
 
# MQTT Client Type – AWS IoT Custom
 
# MQTT Client Type – AWS IoT Custom
 
# Device ID – enter device IMEI (optional)  
 
# Device ID – enter device IMEI (optional)  
 
# Leave Data and Command Topics unchanged.
 
# Leave Data and Command Topics unchanged.
−
<br>
+
<br><br>
 
Save the configuration to the device.
 
Save the configuration to the device.
   −
[[File:AWS_MQTT_13.png|frameless|alt=|center|934x425px]]
+
[[File:AWS_GPRS_settings.png|934x425px]]
−
<div style="text-align: center;">Figure 13. GPRS Settings for MQTT AWS IoT Custom</div>
+
<div style="text-align: center;">Figure 27. GPRS Settings for MQTT AWS IoT</div>
 +
 
 +
== '''Checking received data and sending commands in the AWS IoT core'''==
 +
The data received from the device can be found in the MQTT test client, which can be found above “Manage” in the sidebar on the left.
 +
[[File:MQTT_test_client_location.png|934x425px]]
 +
<div style="text-align: center;">Figure 28. MQTT test client location</div>
 +
 
   −
== '''Run the demo'''==
  −
The data received from the device can be found in the MQTT test client, which can be found in the bottom of sidebar on the left.
   
To see incoming data, subscribe to topic - *DeviceImei*/data . Or subscribe to # to see all incoming outgoing data in the Topics.
 
To see incoming data, subscribe to topic - *DeviceImei*/data . Or subscribe to # to see all incoming outgoing data in the Topics.
−
[[File:AWS_MQTT_14.png|frameless|alt=|center|934x425px]]
+
[[File:MQTT_test_client.jpg|934x425px]]
−
<div style="text-align: center;">Figure 14. Subscribing to data topic</div>
+
<div style="text-align: center;">Figure 29. MQTT test client</div>
−
Incoming data is received in JSON format, for e.g.:
+
 
 +
 
 +
Incoming data is received in JSON format, for e.g.:<br>
 +
[[File:Received_data_format.png|934x425px]]
 +
<div style="text-align: center;">Figure 30. Received data format</div>
 +
 
 +
 
 +
To send SMS/GPRS commands to the device subscribe to a topic name - *DeviceIMEI*/commands, and, in the same MQTT test client window select Publish to a topic. Enter topic name - *DeviceIMEI*/commands. In the Message payload enter wanted GPRS/SMS command in following format and press Publish:
 +
<br><br><code> {“CMD”: “<Command>”} </code><br>
 +
[[File:Sending_a_command.jpg|934x425px]]
 +
<div style="text-align: center;">Figure 31. Sending Command in AWS IoT Core</div>
   −
[[File:AWS_MQTT_15.png|frameless|alt=|center|934x425px]]
  −
<div style="text-align: center;">Figure 15. Received data format</div>
  −
To send SMS/GPRS commands to the device, in the same MQTT test client window select Publish to a topic. Enter topic name - *DeviceIMEI*/commands . In the Message payload enter wanted GPRS/SMS command in following format and press Publish:
     −
[[File:AWS_MQTT_16.png|frameless|alt=|center|934x425px]]
  −
<div style="text-align: center;">Figure 16. Sending Command in AWS IoT Core</div>
   
The response to the command will be shown in the Data topic:
 
The response to the command will be shown in the Data topic:
 +
[[File:Response_to_command.jpg|934x425px]]
 +
<div style="text-align: center;">Figure 32. Response to a command in the data topic, the command was published in command topic</div>
 +
 +
== '''Debugging''' ==
 +
In the situation when the issue with information upload appears, device internal logs can be taken directly from device configuration software ([[FMM130_Status_info#Maintenance|instructions]]), via Terminal.exe by connecting selecting device USB connection port, or by receiving internal logs via FotaWEB in [[FOTA_WEB_Devices#Create_Task|task section]].
 +
 +
== '''Troubleshooting''' ==
   −
[[File:AWS_MQTT_17.png|frameless|alt=|center|934x425px]]
+
The information can be submitted to Teltonika HelpDesk and Teltonika engineers will assist with troubleshooting. For a more detailed information regarding what information should be collected for debugging, please visit the dedicated page on [[What_debug_information_should_be_collected?|Teltonika Wiki]].
−
<div style="text-align: center;">Figure 17. Response to a command in the data topic, the command was published in command topic</div>
+
<br>
 +
Alternatively, Teltonika has a [https://community.teltonika-gps.com/ Crowd Support Forum] dedicated for troubleshooting, where engineers are actively solving problems.
Retrieved from "https://wiki.teltonika-gps.com/view/Special:MobileDiff/89116"

Navigation menu