From c031cc00a81d4482bedaa2ab0bc98117cb21b850 Mon Sep 17 00:00:00 2001 From: Eric Harmeling Date: Mon, 7 Jan 2019 21:28:50 +0000 Subject: [PATCH] Jan 2019 documentation updates --- doc_source/.gitignore | 1 + doc_source/ble-demo.md | 250 +++++++++++++++---- doc_source/code-sign-policy.md | 6 +- doc_source/create-ota-user-policy.md | 6 +- doc_source/create-service-role.md | 40 ++- doc_source/dev-guide-ota-security.md | 12 +- doc_source/dev-guide-ota-workflow.md | 2 +- doc_source/device-tester-for-freertos-ug.md | 140 ++--------- doc_source/dg-ota-bucket.md | 8 +- doc_source/freertos-ble-library.md | 2 +- doc_source/freertos-ble-mobile.md | 57 ++++- doc_source/freertos-dev-guide.md | 3 +- doc_source/freertos-getting-started.md | 16 +- doc_source/freertos-lib-cloud-mqtt.md | 36 +-- doc_source/freertos-lib-cloud-shadows.md | 6 +- doc_source/freertos-mds-projects-struct.md | 40 +-- doc_source/freertos-ocw-ug.md | 20 +- doc_source/freertos-ota-dev.md | 2 +- doc_source/freertos-prereqs.md | 57 +++-- doc_source/freertos-qualification-program.md | 3 + doc_source/freertos-wifi.md | 4 +- doc_source/getting_started_espressif.md | 51 ++-- doc_source/getting_started_infineon.md | 12 +- doc_source/getting_started_mch.md | 12 +- doc_source/getting_started_mediatek.md | 175 +++++++++++++ doc_source/getting_started_nordic.md | 72 +++--- doc_source/getting_started_nxp.md | 12 +- doc_source/getting_started_renesas.md | 190 ++++++++++++++ doc_source/getting_started_st.md | 24 +- doc_source/getting_started_ti.md | 38 +-- doc_source/getting_started_windows.md | 6 +- doc_source/getting_started_xilinx.md | 18 +- doc_source/gg-demo.md | 8 +- doc_source/index.md | 19 +- doc_source/ota-agent-library.md | 14 +- doc_source/ota-cli-workflow.md | 12 +- doc_source/ota-code-sign-cert-esp.md | 2 +- doc_source/ota-code-sign-cert-mchip.md | 2 +- doc_source/ota-code-sign-cert-ti.md | 4 +- doc_source/ota-code-sign-cert-win.md | 2 +- doc_source/ota-code-sign-cert.md | 11 +- doc_source/ota-prereqs.md | 15 +- doc_source/secure-sockets.md | 16 +- doc_source/what-is-amazon-freertos.md | 20 +- 44 files changed, 970 insertions(+), 476 deletions(-) create mode 100644 doc_source/.gitignore create mode 100755 doc_source/freertos-qualification-program.md create mode 100755 doc_source/getting_started_mediatek.md create mode 100755 doc_source/getting_started_renesas.md diff --git a/doc_source/.gitignore b/doc_source/.gitignore new file mode 100644 index 0000000..e43b0f9 --- /dev/null +++ b/doc_source/.gitignore @@ -0,0 +1 @@ +.DS_Store diff --git a/doc_source/ble-demo.md b/doc_source/ble-demo.md index 64a62f1..b1412af 100755 --- a/doc_source/ble-demo.md +++ b/doc_source/ble-demo.md @@ -9,57 +9,131 @@ Amazon FreeRTOS BLE includes three demo applications: -### [MQTT over BLE](#ble-demo-mqtt) Demo +### [MQTT over BLE](#ble-demo-mqtt) Demo This application demonstrates how to use the MQTT over BLE service\. -### [Wi\-Fi Provisioning](#ble-demo-wifi) Demo +### [Wi\-Fi Provisioning](#ble-demo-wifi) Demo This application demonstrates how to use the Wi\-Fi Provisioning service\. -### [Generic Attributes Server](#ble-demo-server) Demo +### [Generic Attributes Server](#ble-demo-server) Demo This application demonstrates how to use the Amazon FreeRTOS BLE middleware APIs to create a simple GATT server\. ## Prerequisites -To follow along with these demos, you need a microcontroller with Bluetooth Low Energy capabilities\. +To follow along with these demos, you need a microcontroller with Bluetooth Low Energy capabilities\. You also need the [iOS SDK for Amazon FreeRTOS Bluetooth Devices](freertos-ble-mobile.md#freertos-ble-ios) or the [Android SDK for Amazon FreeRTOS Bluetooth Devices](freertos-ble-mobile.md#freertos-ble-android)\. -Before you begin, do the following: +### Set Up AWS IoT and Amazon Cognito for Amazon FreeRTOS BLE -### Set Up AWS IoT +To connect your devices to AWS IoT across MQTT, you need to set up AWS IoT and Amazon Cognito\. -To set up AWS IoT, you need to do the following: -+ Set up an AWS account\. -+ Register your device as an AWS IoT thing\. -+ Download your AWS IoT credentials\. +**To set up AWS IoT** -For more information about setting up AWS IoT, see the [AWS IoT Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/)\. +1. Set up an AWS account on [https://aws\.amazon\.com](https://aws.amazon.com)\. -### Set Up Amazon Cognito +1. Open the [AWS IoT console](https://console.aws.amazon.com/iot/), and from the navigation pane, choose **Manage**, and then choose **Things**\. -To set up Amazon Cognito, you need to do the following: -+ Set up an AWS account\. -+ Create an Amazon Cognito user pool\. -+ Create an Amazon Cognito identity pool\. -+ Attach an IAM policy to the authenticated identity\. +1. Choose **Create**, and then choose **Create a single thing**\. -For more information about setting up Amazon Cognito, see the [Amazon Cognito Developer Guide](https://docs.aws.amazon.com/cognito/latest/developerguide/)\. +1. Enter a name for your device, and then choose **Next**\. -### Set Up Your Environment +1. If you are connecting your microcontroller to the cloud through a mobile device, choose **Create thing without certificate**\. Because the Mobile SDKs use Amazon Cognito for device authentication, you do not need to create a device certificate for demos that use BLE\. -To set up your enviroment, do the following: -+ Set up your microcontroller's environment with Amazon FreeRTOS and the Amazon FreeRTOS BLE library\. You can download Amazon FreeRTOS from [GitHub](https://github.com/aws/amazon-freertos)\. + If you are connecting your microcontroller to the cloud directly over Wi\-Fi, choose **Create certificate**, choose **Activate**, and then download the thing's certificate, public key, and private key\. - For information about getting started with Amazon FreeRTOS on an Amazon FreeRTOS\-qualified microcontroller, see information for your board in [Getting Started with Amazon FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-getting-started.html)\. +1. Choose the thing that you just created from the list of registered things, and then choose **Interact** from your thing's page\. Make a note of the AWS IoT REST API endpoint\. + +For more information about setting up, see the [Getting Started with AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html)\. + +**To create an Amazon Cognito user pool** + +1. Open the Amazon Cognito console, and choose **Manage User Pools**\. + +1. Choose **Create a user pool**\. + +1. Give the user pool a name, and then choose **Review defaults**\. + +1. From the navigation pane, choose **App clients**, and then choose **Add an app client**\. + +1. Enter a name for the app client, and then choose **Create app client**\. + +1. From the navigation pane, choose **Review**, and then choose **Create pool**\. + + Make a note of the pool ID that appears on the **General Settings** page of your user pool\. + +1. From the navigation pane, choose **App clients**, and then choose **Show details**\. Make a note of the app client ID and app client secret\. + +**To create an Amazon Cognito identity pool** + +1. Open the Amazon Cognito console, and choose **Manage Identity Pools**\. + +1. Enter a name for your identity pool\. + +1. Expand **Authentication providers**, choose the **Cognito** tab, and then enter your user pool ID and app client ID\. + +1. Choose **Create Pool**\. + +1. Expand **View Details**, and make a note of the two IAM role names\. Choose **Allow** to create the IAM roles for authenticated and unauthenticated identities to access Amazon Cognito\. + +1. Choose **Edit identity pool**\. Make a note of the identity pool ID\. It should be of the form `us-west-2:12345678-1234-1234-1234-123456789012`\. + +For more information about setting up Amazon Cognito, see the [Getting Started with Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-getting-started.html)\. + +**To create and attach an IAM policy to the authenticated identity** + +1. Open the IAM console, and from the navigation pane, choose **Roles**\. + +1. Find and choose your authenticated identity's role, choose **Attach policies**, and then choose **Add inline policy**\. + +1. Choose the **JSON** tab, and paste the following JSON: + + ``` + { + "Version":"2012-10-17", + "Statement":[ + { + "Effect":"Allow", + "Action":[ + "iot:AttachPolicy", + "iot:AttachPrincipalPolicy", + "iot:Connect", + "iot:Publish", + "iot:Subscribe", + "iot:Receive", + "iot:GetThingShadow", + "iot:UpdateThingShadow", + "iot:DeleteThingShadow" + ], + "Resource":[ + "*" + ] + } + ] + } + ``` + +1. Choose **Review policy**, enter a name for the policy, and then choose **Create policy**\. + +Keep your AWS IoT and Amazon Cognito information on hand\. You need the endpoint and IDs to authenticate your mobile application with the AWS Cloud\. + +### Set Up Your Amazon FreeRTOS Environment for BLE + +To set up your enviroment, you need to download Amazon FreeRTOS with the [Amazon FreeRTOS Bluetooth Low Energy Library \(Beta\)](freertos-ble-library.md) on your microcontroller, and download and configure the Mobile SDK for Amazon FreeRTOS Bluetooth Devices on your mobile device\. + +**To set up your microcontroller's environment with Amazon FreeRTOS BLE** + +1. Download the `feature/ble-beta` branch of the Amazon FreeRTOS [GitHub](https://github.com/aws/amazon-freertos/tree/feature/ble-beta) repository\. + +1. Set up Amazon FreeRTOS on your microcontroller\. + + For information about getting started with Amazon FreeRTOS on an Amazon FreeRTOS\-qualified microcontroller, see the guide for your board in [Getting Started with Amazon FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-getting-started.html)\. **Note** You can run the demos on any BLE\-enabled microcontroller with Amazon FreeRTOS and ported Amazon FreeRTOS BLE libraries\. Currently, the Amazon FreeRTOS [MQTT over BLE](#ble-demo-mqtt) demo project is fully ported to the following BLE\-enabled devices: [STMicroelectronics STM32L4 Discovery Kit IoT Node](https://docs.aws.amazon.com/freertos/latest/userguide/getting_started_st.html), with the STBTLE\-1S BLE module [Espressif ESP32\-DevKitC and the ESP\-WROVER\-KIT](https://docs.aws.amazon.com/freertos/latest/userguide/getting_started_espressif.html) [Nordic nRF52840\-DK](https://docs.aws.amazon.com/freertos/latest/userguide/getting_started_nordic.html) -+ Install the [Amazon FreeRTOS BLE Mobile SDK Demo Application](#ble-sdk-app) on your Android or iOS device\. The demo application is a common component of the demos\. - - For information about installing the demo app, see the GitHub README files for the [Amazon FreeRTOS BLE Mobile SDK for Android](https://github.com/aws/amazon-freertos-ble-android-sdk/) or the [Amazon FreeRTOS BLE Mobile SDK for iOS](https://github.com/aws/amazon-freertos-ble-ios-sdk/)\. ## Common Components @@ -69,7 +143,7 @@ The Amazon FreeRTOS demo applications have two common components: ### Network Manager -Network Manager manages your microcontroller's network connection\. It is located in your Amazon FreeRTOS directory at `\demos\common\network_manager\aws_iot_network_manager.c`\. If the network manager is enabled for both Wi\-Fi and BLE, the demos start with BLE by default\. If the BLE connection is disrupted, and your board is Wi\-Fi\-enabled, the Network Manager switches to an available Wi\-Fi connection to prevent you from disconnecting from the network\. +Network Manager manages your microcontroller's network connection\. It is located in your Amazon FreeRTOS directory at `\demos\common\network_manager\aws_iot_network_manager.c`\. If the Network Manager is enabled for both Wi\-Fi and BLE, the demos start with BLE by default\. If the BLE connection is disrupted, and your board is Wi\-Fi\-enabled, the Network Manager switches to an available Wi\-Fi connection to prevent you from disconnecting from the network\. To enable a network connection type with the Network Manager, add the network connection type to the `configENABLED_NETWORKS` parameter in `demos/vendor/board/common/config_files/aws_iot_network_config.h`\. For example, if you have both BLE and Wi\-Fi enabled, the line that starts with `#define configENABLED_NETWORKS` in `aws_iot_network_config.h` reads as follows: @@ -77,22 +151,88 @@ To enable a network connection type with the Network Manager, add the network co #define configENABLED_NETWORKS ( AWSIOT_NETWORK_TYPE_BLE | AWSIOT_NETWORK_TYPE_WIFI ) ``` -To get a list of currently supported network connection types, see `lib\include\aws_iot_network_manager.h`\. +To get a list of currently supported network connection types, see the lines that begin with `#define AWSIOT_NETWORK_TYPE` in `lib\include\aws_iot_network.h`\. ### Amazon FreeRTOS BLE Mobile SDK Demo Application -Each demo uses the Amazon FreeRTOS BLE Mobile SDK demo application, which can be found in the [BLE Android SDK](https://github.com/aws/amazon-freertos-ble-android-sdk/tree/master/FreeRTOSDemo/Examples) or the [BLE iOS SDK](https://github.com/aws/amazon-freertos-ble-ios-sdk/tree/master/FreeRTOSDemo/Examples) under `FreeRTOSDemo/Examples`\. In this example, we use the iOS version of the demo mobile application\. +The Amazon FreeRTOS BLE Mobile SDK demo application is located in the [Android SDK for Amazon FreeRTOS Bluetooth Devices](https://github.com/aws/amazon-freertos-ble-android-sdk/tree/beta/app) under `amazon-freertos-ble-android-sdk/app` and the [iOS SDK for Amazon FreeRTOS Bluetooth Devices](https://github.com/aws/amazon-freertos-ble-ios-sdk/tree/beta/Example/AmazonFreeRTOSDemo) under `amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo`\. In this example, we use screenshots of the iOS version of the demo mobile application\. -To discover and establish secure connections with your microcontroller across BLE with the demo mobile application, for each demo, do the following: +**To configure the iOS SDK demo application** -1. Run the [MQTT over BLE](#ble-demo-mqtt), [Wi\-Fi Provisioning](#ble-demo-wifi), or [Generic Attributes Server](#ble-demo-server) demo on your microcontroller\. +When you define configuration variables, use the format of the placeholder values provided in the configuration files\. -1. Start the BLE mobile SDK demo application on your mobile device\. +1. Confirm that you the [iOS SDK for Amazon FreeRTOS Bluetooth Devices](freertos-ble-mobile.md#freertos-ble-ios) is installed\. -1. Confirm that your microcontroller appears under **Devices** on the BLE mobile SDK demo app\. +1. Issue the following command from `amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo/`: + + ``` + $ sudo pod install + ``` + +1. Open the project with Xcode, and change the signing developer account to your account\. + +1. Open `amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo/AmazonFreeRTOSDemo/Amazon/AmazonConstants.swift`, and redefine the following variables: + + `region`: Your AWS Region\. + + `iotPolicyName`: Your AWS IoT policy name\. + + `mqttCustomTopic`: The MQTT topic that you want to publish to\. + +1. Open `amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo/AmazonFreeRTOSDemo/Support/awsconfiguration.json`\. + + Under `CognitoIdentity`, redefine the following variables: + + `PoolId`: Your Amazon Cognito identity pool ID\. + + `Region`: Your AWS Region\. + + Under `CognitoUserPool`, redefine the following variables: + + `PoolId`: Your Amazon Cognito user pool ID\. + + `AppClientId`: Your app client ID\. + + `AppClientSecret`: Your app client secret\. + + `Region`: Your AWS Region\. + +**To configure the Android SDK demo application** + +When you define configuration variables, use the format of the placeholder values provided in the configuration files\. + +1. Confirm that the [Android SDK for Amazon FreeRTOS Bluetooth Devices](freertos-ble-mobile.md#freertos-ble-android) is installed\. + +1. Open `amazon-freertos-ble-android-sdk/app/src/main/java/com/amazon/aws/freertosandroid/AuthenticatorActivity.java`, and redefine the following variables: + + `AWS_IOT_POLICY_NAME`: Your AWS IoT policy name\. + + `AWS_IOT_REGION`: Your AWS Region\. + + `COGNITO_POOL_ID`: Your Amazon Cognito identity pool ID\. + + `COGNITO_REGION`: Your AWS Region\. + +1. Open `amazon-freertos-ble-android-sdk/app/src/main/java/com/amazon/aws/freertosandroid/MainActivity.java`, and redefine the following variables: + + `BLE_DEVICE_MAC_ADDR`: The MAC address of your device\. + + `BLE_DEVICE_NAME`: Your device name\. + + `MTU`: The desired MTU between your microcontroller and mobile device\. + +1. Open `amazon-freertos-ble-android-sdk/app/src/main/res/raw/awsconfiguration.json`\. + + Under `CognitoIdentity`, redefine the following variables: + + `PoolId`: Your Amazon Cognito identity pool ID\. + + `Region`: Your AWS Region\. + + Under `CognitoUserPool`, redefine the following variables: + + `PoolId`: Your Amazon Cognito user pool ID\. + + `AppClientId`: Your app client ID\. + + `AppClientSecret`: Your app client secret\. + + `Region`: Your AWS Region\. + +**To discover and establish secure connections with your microcontroller over BLE** + +1. Run the BLE demo project on your microcontroller\. + +1. Run the BLE Mobile SDK demo application on your mobile device\. + + To start the demo application in the Android SDK from the command line, run the following command: + + ``` + $ ./gradlew installDebug + ``` + +1. Confirm that your microcontroller appears under **Devices** on the BLE Mobile SDK demo app\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/ble-device-list1.png) **Note** -Only devices with Amazon FreeRTOS and the device information service \(`\lib\bluetooth_low_energy\services\device_information`\) appear in the list\. +All devices with Amazon FreeRTOS and the device information service \(`\lib\bluetooth_low_energy\services\device_information`\) that are in range appear in the list\. 1. Choose your microcontroller from the list of devices\. The application establishes a connection with the board, and a green line appears next to the connected device\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/ble-device-list2.png) @@ -111,7 +251,7 @@ The BLE Mobile SDK demo application uses Amazon Cognito for user authentication\ ## MQTT over BLE -In the MQTT over BLE demo, your microcontroller publishes messages to the AWS IoT cloud through an MQTT proxy\. +In the MQTT over BLE demo, your microcontroller publishes messages to the AWS Cloud through an MQTT proxy\. **To subscribe to a demo MQTT topic** @@ -122,17 +262,19 @@ In the MQTT over BLE demo, your microcontroller publishes messages to the AWS Io 1. In **Subscription topic**, enter **freertos/demos/echo**, and then choose **Subscribe to topic**\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/ble-hw-test-console.png) -You can run the MQTT demo across a BLE or Wi\-Fi connection\. The configuration of the [Network Manager](#ble-demo-network-manager) determines which connection type is used\. +You can run the MQTT demo over a BLE or Wi\-Fi connection\. The configuration of the [Network Manager](#ble-demo-network-manager) determines which connection type is used\. -If you use BLE to pair the microcontroller with your mobile device, the MQTT messages are routed through the BLE mobile SDK demo application on your mobile device\. +If you use BLE to pair the microcontroller with your mobile device, the MQTT messages are routed through the BLE Mobile SDK demo application on your mobile device\. -If you use Wi\-Fi, the demo is the same as the MQTT Hello World demo project located in [https://github.com/aws/amazon-freertos/tree/master/demos/vendor/board/ide](https://github.com/aws/amazon-freertos/tree/master/demos/vendor/board/ide)\. That demo is used in most of the [Getting Started with Amazon FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-getting-started.html) demo projects\. +If you use Wi\-Fi, the demo is the same as the MQTT Hello World demo project located at [demos/common/mqtt/aws\_hello\_world\.c](https://github.com/aws/amazon-freertos/blob/master/demos/common/mqtt/aws_hello_world.c)\. That demo is used in most of the [Getting Started with Amazon FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-getting-started.html) demo projects\. **To enable the demo** -If you have already enabled the demo by following the instructions in the getting started guide for your device, you can skip these instructions\. +If you have already enabled the BLE demo by following the instructions in the Getting Started guide for your device, you can skip these instructions\. -1. Confirm that the MQTT over BLE and Wi\-Fi Provisioning services are enabled in `lib\utils\aws_ble_services_init.c`\. The services are enabled by default\. +1. Enable the Wi\-Fi Provisioning service\. Open `demos/vendor/board/common/config_files/aws_ble_config.h`, and set `#define bleconfigENABLE_WIFI_PROVISIONING` to `1`\. +**Note** +The Wi\-Fi Provisioning service is disabled by default\. 1. Open `demos\common\demo_runner\aws_demo_runner.c`, and in the demo declarations, uncomment `extern void vStartMQTTBLEEchoDemo( void );`\. In the `DEMO_RUNNER_RunDemos` definition, uncomment `vStartMQTTBLEEchoDemo();`\. @@ -146,7 +288,7 @@ If the Network Manager is configured for BLE, do the following: 1. Make sure that you have paired your board and your mobile device using the [Amazon FreeRTOS BLE Mobile SDK Demo Application](#ble-sdk-app)\. -1. From the **Devices**list in the demo mobile app, choose your microcontroller, and then choose **MQTT Proxy** to open the MQTT proxy settings\. +1. From the **Devices** list in the demo mobile app, choose your microcontroller, and then choose **MQTT Proxy** to open the MQTT proxy settings\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/ble-device-list4.png) 1. Touch **Enable MQTT proxy** to enable the MQTT proxy\. The slider should turn green\. @@ -160,12 +302,14 @@ If the Network Manager is configured for BLE, do the following: Wi\-Fi Provisioning is an Amazon FreeRTOS BLE service that allows you to securely send Wi\-Fi network credentials from a mobile device to a microcontroller over BLE\. The source code for the Wi\-Fi Provisioning service can be found at `lib/bluetooth_low_energy/services/wifi_provisioning`\. **Note** -The Wi\-Fi provisioning demo is currently supported on the Espressif ESP32\-DevKitC\. +The Wi\-Fi Provisioning demo is currently supported on the Espressif ESP32\-DevKitC\. The Android version of the demo mobile application does not currently support Wi\-Fi Provisioning\. **To enable the demo** -1. Confirm that the Wi\-Fi Provisioning service is enabled in the `lib\utils\aws_ble_services_init.c` file\. The service is enabled by default\. +1. Enable the Wi\-Fi Provisioning service\. Open `demos/vendor/board/common/config_files/aws_ble_config.h`, and set `#define bleconfigENABLE_WIFI_PROVISIONING` to `1`\. +**Note** +The Wi\-Fi Provisioning service is disabled by default\. 1. Configure the [Network Manager](#ble-demo-network-manager) to enable both BLE and Wi\-Fi\. @@ -184,7 +328,7 @@ The Android version of the demo mobile application does not currently support Wi From the **Scanned Networks** list, choose your network, and then enter the SSID and password, if required\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/ble-wifi-password.png) - The micrcontroller connects to and saves the network\. The network appears under the **Saved Networks**\. + The micrcontroller connects to and saves the network\. The network appears under **Saved Networks**\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/ble-network-config2.png) You can save several networks in the demo mobile app\. When you restart the application and demo, the microcontroller connects to the first available saved network, starting from the top of the **Saved Networks** list\. @@ -195,22 +339,32 @@ To change the network priority order or delete networks, on the **Network Config ## Generic Attributes Server -In this example, a demo Generic Attributes \(GATT\) server application on your microcontroller sends a simple counter value to the [Amazon FreeRTOS BLE Mobile SDK Demo Application](#ble-sdk-app) that is used for [MQTT over BLE](#ble-demo-mqtt) and [Wi\-Fi Provisioning](#ble-demo-wifi)\. +In this example, a demo Generic Attributes \(GATT\) server application on your microcontroller sends a simple counter value to the [Amazon FreeRTOS BLE Mobile SDK Demo Application](#ble-sdk-app)\. Using the BLE Mobile SDKs, you can create your own GATT client for a mobile device that connects to the GATT server on your microcontroller and runs in parallel with the demo mobile application\. +**To enable the demo** + +1. Enable the BLE GATT demo\. In `demos/vendor/board/common/config_files/aws_ble_config.h`, add `#define bleconfigENABLE_GATT_DEMO ( 1 )` to the list of define statements\. +**Note** +The BLE GATT demo is disabled by default\. + +1. Open `demos\common\demo_runner\aws_demo_runner.c`, and in the demo declarations, uncomment `extern void vStartMQTTBLEEchoDemo( void );`\. In the `DEMO_RUNNER_RunDemos` definition, uncomment `vStartMQTTBLEEchoDemo();`\. + **To run the demo** 1. Build and run the demo project on your microcontroller\. 1. Make sure that you have paired your board and your mobile device using the [Amazon FreeRTOS BLE Mobile SDK Demo Application](#ble-sdk-app)\. -1. From the **Devices** list in the mobile SDK app, choose your board, and then choose **Custom GATT MQTT** to open the custom GATT service options\. +1. From the **Devices** list in the app, choose your board, and then choose **MQTT Proxy** to open the MQTT proxy options\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/ble-device-list4.png) -1. Touch **Enable MQTT proxy** to enable the MQTT proxy\. The slider should turn green\. - -1. Choose **Start Counter** to start publishing data to the `freertos/demos/echo` MQTT topic\. +1. Touch **Enable MQTT proxy** to enable the MQTT proxy\. The slider should turn green\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/ble-device-proxy.png) +1. Return to the **Devices** list, choose your board, and then choose **Custom GATT MQTT** to open the custom GATT service options\. + +1. Choose **Start Counter** to start publishing data to the `freertos/demos/echo` MQTT topic\. + After you enable the MQTT proxy, Hello World and incrementing counter messages appear on the `freertos/demos/echo` topic\. \ No newline at end of file diff --git a/doc_source/code-sign-policy.md b/doc_source/code-sign-policy.md index 62c96ce..9567ea0 100755 --- a/doc_source/code-sign-policy.md +++ b/doc_source/code-sign-policy.md @@ -1,8 +1,8 @@ -# Granting Access to Code Signing for Amazon FreeRTOS +# Grant Access to Code Signing for AWS IoT -In production environments, you should digitally sign your firmware update to ensure the authenticity and integrity of the update\. You can sign your update manually or you can use Code Signing for Amazon FreeRTOS to sign your code\. To use Code Signing for Amazon FreeRTOS, you must grant your IAM user account access to Code Signing for Amazon FreeRTOS\. +In production environments, you should digitally sign your firmware update to ensure the authenticity and integrity of the update\. You can sign your update manually or you can use Code Signing for AWS IoT to sign your code\. To use Code Signing for Amazon FreeRTOS, you must grant your IAM user account access to Code Signing for Amazon FreeRTOS\. -**To grant your IAM user account permissions for Code Signing for Amazon FreeRTOS** +**To grant your IAM user account permissions for Code Signing for AWS IoT** 1. Sign in to the [https://console\.aws\.amazon\.com/iam/](https://console.aws.amazon.com/iam/)\. diff --git a/doc_source/create-ota-user-policy.md b/doc_source/create-ota-user-policy.md index 8fe9895..7496e98 100755 --- a/doc_source/create-ota-user-policy.md +++ b/doc_source/create-ota-user-policy.md @@ -1,4 +1,4 @@ -# Creating an OTA User Policy +# Create an OTA User Policy You must grant your IAM user permission to perform over\-the\-air updates\. Your IAM user must have permissions to: + Access the S3 bucket where your firmware updates are stored\. @@ -7,10 +7,10 @@ You must grant your IAM user permission to perform over\-the\-air updates\. Your + Access Amazon FreeRTOS OTA updates\. + Access AWS IoT jobs\. + Access IAM\. -+ Access Code Signing for Amazon FreeRTOS\. ++ Access Code Signing for AWS IoT\. + List Amazon FreeRTOS hardware platforms\. -To grant your IAM user the required permissions, create an OTA user policy and then attach it to your IAM user\. For more information, see [IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html)\. +To grant your IAM user the required permissions, create an OTA user policy and then attach it to your IAM user\. For more information, see [IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html)\. **To create an OTA user policy** diff --git a/doc_source/create-service-role.md b/doc_source/create-service-role.md index d639608..acf7e5d 100755 --- a/doc_source/create-service-role.md +++ b/doc_source/create-service-role.md @@ -1,6 +1,6 @@ -# Creating an OTA Update Service Role +# Create an OTA Update Service Role -The OTA Update service assumes this role to create and manage OTA update jobs on your behalf\. +The OTA Update service assumes this role to create and manage OTA update jobs on your behalf\. **To create an OTA service role** @@ -14,9 +14,9 @@ The OTA Update service assumes this role to create and manage OTA update jobs on 1. Choose **IoT** from the list of AWS services\. -1. Under **Select your use case**, choose **IoT allows IoT to call AWS services on your behalf**\. +1. Under **Select your use case**, choose **IoT**\. -1. Choose **Next: Permissions**\. +1. Choose **Next: Tags**\. 1. Choose **Next: Review**\. @@ -28,15 +28,15 @@ For more information about IAM roles, see [IAM Roles](https://docs.aws.amazon.co 1. In the search box on the IAM console page, enter the name of your role, and then choose it from the list\. -1. Choose **Attach policy**\. +1. Choose **Attach policies**\. -1. In the **Search** box, enter **AmazonFreeRTOSOTAUpdate**\. In the list of managed policies, select **AmazonFreeRTOSOTAUpdate** , and then choose **Attach policy**\. +1. In the **Search** box, enter **AmazonFreeRTOSOTAUpdate**\. In the list of managed policies, check **AmazonFreeRTOSOTAUpdate** , and then choose **Attach policy**\. **To add the required permissions to your OTA service role** 1. In the search box on the IAM console page, enter the name of your role and then choose it from the list\. -1. In the lower right, choose **Add inline policy**\. +1. Choose **Add inline policy**\. 1. Choose the **JSON** tab\. @@ -48,30 +48,18 @@ For more information about IAM roles, see [IAM Roles](https://docs.aws.amazon.co "Statement": [ { "Effect": "Allow", - "Action": "iam:PassRole", - "Resource": - "arn:aws:iam:::role/" + "Action": [ + "s3:GetObjectVersion", + "s3:GetObject" + ], + "Resource": "arn:aws:s3:::/*" } ] } ``` - If you provide your own bucket name, use the following policy to grant your service role access to your bucket: - - ``` - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "s3:GetObjectVersion", - "s3:GetObject" - ], - "Resource": "arn:aws:s3:::/*" - } - ] - ``` + This policy grants your OTA service role permission to read Amazon S3 objects\. 1. Choose **Review policy**\. -1. Enter a name for the policy and then choose **Create policy**\. \ No newline at end of file +1. Enter a name for the policy, and then choose **Create policy**\. \ No newline at end of file diff --git a/doc_source/dev-guide-ota-security.md b/doc_source/dev-guide-ota-security.md index 17f54a4..eacc539 100755 --- a/doc_source/dev-guide-ota-security.md +++ b/doc_source/dev-guide-ota-security.md @@ -6,18 +6,18 @@ Connection security The OTA Update Manager relies on existing security mechanisms, like TLS mutual authentication, used by AWS IoT\. OTA update traffic passes through the AWS IoT device gateway and uses AWS IoT security mechanisms\. Each incoming and outgoing MQTT message through the device gateway undergoes strict authentication and authorization\. Authenticity and integrity of OTA updates -Firmware can be digitally signed before an OTA update to ensure that it is from a reliable source and has not been tampered with\. The Amazon FreeRTOS OTA Update Manager uses the Code Signing for Amazon FreeRTOS to automatically sign your firmware\. For more information, see [Code Signing for Amazon FreeRTOS](http://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html)\. The OTA agent, which runs on your devices, performs integrity checks on the firmware when it arrives on the device\. +Firmware can be digitally signed before an OTA update to ensure that it is from a reliable source and has not been tampered with\. The Amazon FreeRTOS OTA Update Manager uses the Code Signing for AWS IoT to automatically sign your firmware\. For more information, see [Code Signing for AWS IoT](http://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html)\. The OTA agent, which runs on your devices, performs integrity checks on the firmware when it arrives on the device\. Operator security Every API call made through the control plane API undergoes standard IAM Signature Version 4 authentication and authorization\. To create a deployment, you must have permissions to invoke the `CreateDeployment`, `CreateJob`, and `CreateStream` APIs\. In addition, in your Amazon S3 bucket policy or ACL, you must give read permissions to the AWS IoT service principal so that the firmware update stored in Amazon S3 can be accessed during streaming\. -## Code Signing for Amazon FreeRTOS +## Code Signing for AWS IoT -The AWS IoT console uses [Code Signing for Amazon FreeRTOS](http://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html) to automatically sign your firmware image for any device supported by AWS IoT\. +The AWS IoT console uses [Code Signing for AWS IoT](http://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html) to automatically sign your firmware image for any device supported by AWS IoT\. -Code Signing for Amazon FreeRTOS uses a certificate and private key that you import into ACM\. You can use a self–signed certificate for testing, but we recommend that you obtain a certificate from a well–known commercial certificate authority \(CA\)\. +Code Signing for AWS IoT uses a certificate and private key that you import into ACM\. You can use a self–signed certificate for testing, but we recommend that you obtain a certificate from a well–known commercial certificate authority \(CA\)\. -Code–signing certificates use the X\.509 version 3 **Key Usage** and **Extended Key Usage** extensions\. The **Key Usage** extension is set to `Digital Signature` and the **Extended Key Usage** extension is set to `Code Signing`\. For more information about signing your code image, see the [Code Signing for Amazon FreeRTOS Developer Guide](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html) and the [Code Signing for Amazon FreeRTOS API Reference](https://docs.aws.amazon.com/signer/latest/api/Welcome.html)\. +Code–signing certificates use the X\.509 version 3 **Key Usage** and **Extended Key Usage** extensions\. The **Key Usage** extension is set to `Digital Signature` and the **Extended Key Usage** extension is set to `Code Signing`\. For more information about signing your code image, see the [Code Signing for AWS IoT Developer Guide](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html) and the [Code Signing for AWS IoT API Reference](https://docs.aws.amazon.com/signer/latest/api/Welcome.html)\. **Note** -You can download the Code Signing for Amazon FreeRTOS SDK from [https://tools\.signer\.aws\.a2z\.com/awssigner\-tools\-v2\.zip](https://tools.signer.aws.a2z.com/awssigner-tools-v2.zip)\. \ No newline at end of file +You can download the Code Signing for AWS IoT SDK from [https://tools\.signer\.aws\.a2z\.com/awssigner\-tools\-v2\.zip](https://tools.signer.aws.a2z.com/awssigner-tools-v2.zip)\. \ No newline at end of file diff --git a/doc_source/dev-guide-ota-workflow.md b/doc_source/dev-guide-ota-workflow.md index 57ecaae..7e83642 100755 --- a/doc_source/dev-guide-ota-workflow.md +++ b/doc_source/dev-guide-ota-workflow.md @@ -14,7 +14,7 @@ You can use the AWS IoT console or the AWS CLI to create an OTA update\. The con 1. If you are manually signing your firmware, sign and then upload the signed firmware image to your Amazon S3 bucket\. - If you are using Code Signing for Amazon FreeRTOS, upload your unsigned firmware image to an Amazon S3 bucket\. + If you are using Code Signing for AWS IoT, upload your unsigned firmware image to an Amazon S3 bucket\. 1. Create an OTA update\. diff --git a/doc_source/device-tester-for-freertos-ug.md b/doc_source/device-tester-for-freertos-ug.md index 7de0a4c..9c9b595 100755 --- a/doc_source/device-tester-for-freertos-ug.md +++ b/doc_source/device-tester-for-freertos-ug.md @@ -72,11 +72,11 @@ To add library porting layers for Amazon FreeRTOS device libraries \(TCP/IP, WiF 1. Implement the `configPRINT_STRING()` method before running AWS IoT Device Tester tests\. AWS IoT Device Tester calls the `configPRINT_STRING()` macro to output test results as human\-readable ASCII strings\. -1. Port the drivers to implement the Amazon FreeRTOS library's interfaces\. For more information, see the [Amazon FreeRTOS Qualification Developer Guide](https://github.com/aws/amazon-freertos/blob/master/tests/Amazon%20FreeRTOS%20Qualification%20Program%20Developer%20Guide.pdf)\. +1. Port the drivers to implement the Amazon FreeRTOS library's interfaces\. For more information, see the [Amazon FreeRTOS Qualification Developer Guide](https://github.com/aws/amazon-freertos/blob/master/tests/Amazon%20FreeRTOS%20Qualification%20Developer%20Guide.pdf)\. ### Configure Your AWS Credentials -You must configure your AWS credentials in the `/devicetester_afreertos_[win|mac|linux]/configs/ config.json`\. You can specify your credentials in one of two ways: +You must configure your AWS credentials in the `/devicetester_afreertos_[win|mac|linux]/configs/config.json`\. You can specify your credentials in one of two ways: + Environment variables + Credentials file @@ -339,7 +339,6 @@ Client Wi\-Fi configuration\. The Wi\-Fi library tests require an MCU board to c `testWifiConfig` Test Wi\-Fi configuration\. The Wi\-Fi library tests require a board to connect to two access points\. This attribute configures the second access point\. The test Wi\-Fi settings are configured in `$AFR_HOME/tests/common/wifi/aws_test_wifi.c.`\. The following macros are set by using the values found in `aws_test_wifi.c`\. Some of the Wi\-Fi test cases expect the access point to have some security and not to be open\. -If your board does not support Wi\-Fi, you must still include the `clientWifiConfig` and `testWifiConfig` section in your `device.json` file, but you can omit values for these attributes\. + testwifiWIFI\_SSID: The Wi\-Fi SSID as a C string\. + testwifiWIFI\_PASSWORD: The Wi\-Fi password as a C string\. + testwifiWIFI\_SECURITY: The type of Wi\-Fi security used\. One of the following values: @@ -359,7 +358,7 @@ The signing algorithm used by AWS Code Signer while creating the OTA update job\ `awsSignerCertificateArn` The Amazon Resource Name \(ARN\) for the trusted certificate uploaded to AWS Certificate Manager \(ACM\)\. For more information about creating a trusted certificate, see [Creating a Code Signing Certificate](https://docs.aws.amazon.com/freertos/latest/userguide/ota-code-sign-cert.html)\. `awsUntrustedSignerCertificateArn` -The Amazon Resource Name \(ARN\) for a certificate uploaded to ACM which your device should not trust\. This is used to test invalid certificate test cases\. +The Amazon Resource Name \(ARN\) for a code\-signing certificate uploaded to ACM which your device should not trust\. This is used to test invalid certificate test cases\. `compileCodesignerCertificate` Set to `true` if the code\-signer signature verification certificate is not provisioned or flashed, so it must be compiled into the project\. AWS IoT Device Tester fetches the trusted certificate from ACM and compiles it into `aws_codesigner_certifiate.h`\. @@ -437,9 +436,9 @@ If your board does not support Wi\-Fi, you must still include the `clientWifiCon `otaConfiguration` The OTA configuration\. `otaFirmwareFilePath` -The full path to the OTA image created after the build\. +The full path to the OTA image created after the build\. For example, `{{testData.sourcePath}}/`\. `deviceFirmwareFileName` -The name of the OTA firmware file to be downloaded to the board\. +The full file path on the MCU device where the OTA firmware is located\. Some devices do not use this field, but you still must provide a value\. `awsSignerPlatform` The signing algorithm used by AWS Code Signer while creating the OTA update job\. Currently, the possible values for this field are `AmazonFreeRTOS-TI-CC3220SF` and `AmazonFreeRTOS-Default`\. `awsSignerCertificateArn` @@ -453,6 +452,19 @@ Set to `true` if the code\-signer signature verification certificate is not prov The commands to build your code and flash the device might require connectivity or other information about your devices to run successfully\. AWS IoT Device Tester allows you to reference device information in flash and build commands using [JsonPath](http://goessner.net/articles/JsonPath/)\. By using simple JsonPath expressions, you can fetch the required information as specified in your `device.json` file\. +##### Path Variables + +AWS IoT Device Tester defines the following path variables that can be used in command lines and configuration files: + +`{{testData.sourcePath}}` +A variable that expands to the source code path\. + +`{{device.connectivity.serialPort}}` +A variable that expands to the serial port\. + +`{{device.identifiers[?(@.name == 'serialNo')].value}}` +A variable that expands to the serial number of your device\. + ##### AWS IoT Device Tester Variables and Concurrent Testing To enable parallel builds of the source code for different test groups, AWS IoT Device Tester copies the source code to a results folder inside the AWS IoT Device Tester extracted folder\. The source code path in your build or flash command must be referenced using the `testdata.sourcePath` variable\. AWS IoT Device Tester replaces this variable with a temporary path of the copied source code\. @@ -472,13 +484,9 @@ The `userdata.json` file should be located in the `* - Use the following command to run a specific test group: -devicetester\_*\[linux \| mac \| win\_x86\-64\]* run\-suite \-\-suite\-id AFQ\_1 \-\-group\-id ** \-\-pool\-id ** ** +devicetester\_*\[linux \| mac \| win\_x86\-64\]* run\-suite \-\-suite\-id AFQ\_1 \-\-group\-id ** \-\-pool\-id ** \-\-userdata ** `suite-id` and `pool-id` are optional if you are running a single test suite on a single device pool \(that is, you have only one device pool defined in your `device.json` file\)\.AWS IoT Device Tester command line options @@ -520,13 +528,13 @@ After AWS IoT Device Tester executes the qualification test suite, it generates + The aggregate summary of test case results\. + A breakdown of test case results by libraries that were tested based on the device features \(for example, FullWiFi, FullMQTT, and so on\)\. - The `AFQ_report.xml` is a report in standard junit\.xml format, which you can integrate into your exiting CI/CD platforms like Jenkins, Bamboo, and so on\. The report contains the following elements: + The `AFQ_Report.xml` is a report in standard junit\.xml format, which you can integrate into your exiting CI/CD platforms like Jenkins, Bamboo, and so on\. The report contains the following elements: + An aggregate summary of test case results\. + A breakdown of test case results by libraries that were tested based on the device features \(for example, FullWiFi, FullMQTT, and so on\)\. #### Interpreting AWS IoT Device Tester Results -The report section in `awsiotdevicetester_report.xml` or `AFQ_report.xml` lists the tests that were run and the results of the tests\. +The report section in `awsiotdevicetester_report.xml` or `AFQ_Report.xml` lists the tests that were run and the results of the tests\. The first XML tag `` contains the overall summary of the test execution\. For example: @@ -619,7 +627,7 @@ If you are still having issues, see the debugging following process\. #### Where Do I Look? -Start by looking in the `results.xml` file in the `/results/` directory\. This file contains all of the test cases that were run and error snippets for each failure\. To get all of the execution logs, look under `/results//.log` for each test group\. +Start by looking in the `AFQ_Report.xml` file in the `/results/` directory\. This file contains all of the test cases that were run and error snippets for each failure\. To get all of the execution logs, look under `/results//.log` for each test group\. #### Parsing Errors @@ -722,106 +730,4 @@ When AWS IoT Device Tester is run, failures are reported to console with brief m ##### Log Errors -The **\.log file is located in the `/results/` directory\. Each test execution has a unique test ID that is used to create the ** directory\. Individual test group logs are under the ** directory\. Use the AWS IoT console to look up the test group that failed and then open the log file for that group in the `/results/` directory\. The information in this file includes the full build and flash command output, as well as test execution output and more verbose AWS IoT Device Tester console output\. - -##### Path Variables - -AWS IoT Device Tester defines the following path variables that can be used in command lines and configuration files: - -`{{testData.sourcePath}}` -A variable that expands to the source code path\. - -`{{device.connectivity.serialPort}}` -A variable that expands to the serial port\. - -`{{device.identifiers[?(@.name == 'serialNo')].value}}` -A variable that expands to the serial number of your device\. - -##### - -The following is an example `userdata.json` file: - -``` -{ - "sourcePath":"", - "buildTool":{ - "name":"", - "version":"", - "command":[ - ".sh {{testData.sourcePath}}" - ] - }, - "flashTool":{ - "name":"", - "version":"", - "command":[ - ".sh {{device.connectivity.serialPort}} {{testData.sourcePath}}" - ] - }, - "clientWifiConfig":{ - "wifiSSID":"", - "wifiPassword":"", - "wifiSecurityType":"eWiFiSecurityWPA2" - }, - "testWifiConfig":{ - "wifiSSID":"", - "wifiPassword":"", - "wifiSecurityType":"eWiFiSecurityWPA2" - }, - "otaConfiguration":{ - "otaFirmwareFilePath":"{{testData.sourcePath}}/", - "deviceFirmwareFileName":"", - "awsSignerPlatform":"AmazonFreeRTOS-Default", - "awsSignerCertificateArn":"arn:aws:acm:::certificate:", - "awsUntrustedSignerCertificateArn":"arn:aws:acm:::certificate:", - "awsSignerCertificateFileName":"", - "compileCodesignerCertificate":true - } - } -``` - -The following is an example `device.json` file: - -``` -[ - { - "id": "", - "sku": "", - "features": [ - { - "name": "WIFI", - "value": "" - }, - { - "name": "OTA", - "value": "" - }, - { - "name": "TCP/IP", - "value": "Offloaded" - }, - { - "name": "TLS", - "value": "On-chip" - } - ], - "devices": [ - { - "id": "", - "connectivity": { - "protocol": "uart", - "serialPort": "/dev/tty" OR "/dev/tty." - }, - "identifiers": [ - { - "name": "serialNo", - "value": "" - } - ] - } - ] -} -] -``` - -On the Windows platform, the userdata and device configuration files are formatted in the same manner\. Pay close attention to the direction of the path\-separator slashes\. We recommend using the forward slash \(/\) because newer versions of Windows support it\. If you are using Windows 7 or earlier, use the back slash \(\\\)\. \ No newline at end of file +The **\.log file is located in the `/results/` directory\. Each test execution has a unique test ID that is used to create the ** directory\. Individual test group logs are under the ** directory\. Use the AWS IoT console to look up the test group that failed and then open the log file for that group in the `/results/` directory\. The information in this file includes the full build and flash command output, as well as test execution output and more verbose AWS IoT Device Tester console output\. \ No newline at end of file diff --git a/doc_source/dg-ota-bucket.md b/doc_source/dg-ota-bucket.md index ddff43c..bfec01c 100755 --- a/doc_source/dg-ota-bucket.md +++ b/doc_source/dg-ota-bucket.md @@ -1,6 +1,6 @@ # Create an Amazon S3 Bucket to Store Your Update -OTA update files are stored in Amazon S3 buckets\. If you are using Code Signing for Amazon FreeRTOS, the command you use to create a code\-signing job takes a source bucket \(where the unsigned firmware image is located\) and a destination bucket \(where the signed firmware image is written\)\. You can specify the same bucket for both the source and destination\. The file names are changed to GUIDs so the original files are not overwritten\. +OTA update files are stored in Amazon S3 buckets\. If you are using Code Signing for AWS IoT, the command you use to create a code\-signing job takes a source bucket \(where the unsigned firmware image is located\) and a destination bucket \(where the signed firmware image is written\)\. You can specify the same bucket for both the source and destination\. The file names are changed to GUIDs so the original files are not overwritten\. **To create an Amazon S3 bucket** @@ -9,12 +9,8 @@ OTA update files are stored in Amazon S3 buckets\. If you are using Code Signing 1. Choose **Create bucket**\. 1. Type a bucket name, and then choose **Next**\. -**Note** -Your bucket name must begin with `afr-ota`\. -1. On the **Create bucket** page, choose **Versioning**\. - -1. Choose **Enable versioning**, choose **Save**, and then choose **Next**\. +1. Check **Versioning** to keep all versions in the same bucket, and then choose **Next**\. 1. Choose **Next** to accept the default permissions\. diff --git a/doc_source/freertos-ble-library.md b/doc_source/freertos-ble-library.md index fa8235c..5bf9917 100755 --- a/doc_source/freertos-ble-library.md +++ b/doc_source/freertos-ble-library.md @@ -11,7 +11,7 @@ Amazon FreeRTOS supports publishing and subscribing to MQTT topics over Bluetoot ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/blediagram.png) -Using the Amazon FreeRTOS BLE Mobile SDKs, you can write native mobile applications that communicate with the embedded applications on your microcontroller over BLE\. For more information about the Amazon FreeRTOS BLE Mobile SDKs, see [Mobile SDKs for Amazon FreeRTOS Bluetooth Devices](freertos-ble-mobile.md)\. Amazon FreeRTOS BLE uses Amazon Cognito for user authentication on mobile devices\. +Using the Mobile SDKs for Amazon FreeRTOS Bluetooth Devices, you can write native mobile applications that communicate with the embedded applications on your microcontroller over BLE\. For more information about the mobile SDKs, see [Mobile SDKs for Amazon FreeRTOS Bluetooth Devices](freertos-ble-mobile.md)\. In addition to supporting MQTT, the Amazon FreeRTOS BLE library includes services for configuring Wi\-Fi networks\. The Amazon FreeRTOS BLE library also includes some middleware and lower\-level APIs for more direct control over your BLE stack\. The source files for the Amazon FreeRTOS BLE library are located in [https://github.com/aws/amazon-freertos/tree/feature/ble-beta/lib/bluetooth_low_energy](https://github.com/aws/amazon-freertos/tree/feature/ble-beta/lib/bluetooth_low_energy)\. diff --git a/doc_source/freertos-ble-mobile.md b/doc_source/freertos-ble-mobile.md index 64e7dc9..54c6c84 100755 --- a/doc_source/freertos-ble-mobile.md +++ b/doc_source/freertos-ble-mobile.md @@ -5,12 +5,61 @@ | --- | | The Bluetooth Low Energy \(BLE\) Library is in public beta release for Amazon FreeRTOS and is subject to change\. | -You can use the Amazon FreeRTOS BLE Mobile SDKs to create mobile applications that interact with your microcontroller over BLE\. +You can use the Mobile SDKs for Amazon FreeRTOS Bluetooth Devices to create mobile applications that interact with your microcontroller over BLE\. The Mobile SDKs can also communicate with AWS services, using Amazon Cognito for user authentication\. ## Android SDK for Amazon FreeRTOS Bluetooth Devices -Use the Amazon FreeRTOS BLE Android SDK to build Android mobile applications that interact with your microcontroller over BLE\. For more information, see [Amazon FreeRTOS BLE Mobile SDK for Android](https://github.com/aws/amazon-freertos-ble-android-sdk/)\. +Use the Android SDK for Amazon FreeRTOS Bluetooth Devices to build Android mobile applications that interact with your microcontroller over BLE\. The SDK is available on [GitHub](https://github.com/aws/amazon-freertos-ble-android-sdk/)\. -## Android SDK for Amazon FreeRTOS Bluetooth Devices +**To install the Android SDK** -Use the Amazon FreeRTOS BLE iOS SDK to build iOS mobile applications that interact with your microcontroller over BLE\. For more information, see [Amazon FreeRTOS BLE Mobile SDK for iOS](https://github.com/aws/amazon-freertos-ble-ios-sdk/)\. \ No newline at end of file +1. Download the SDK from [GitHub](https://github.com/aws/amazon-freertos-ble-android-sdk/)\. + +1. Open Android Studio, and import the `amazon-freertos-ble-android-sdk/amazonfreertossdk/` directory into your app project\. + +1. In your app's `gradle` file, add the following dependencies: + + ``` + dependencies { + implementation project(":amazonfreertossdk") + } + ``` + +1. In your app's `AndroidManifest.xml` file, add the following permissions: + + ``` + + + + + + + + + + ``` + +For information about setting up and running the demo mobile application that is included with the SDK, see [Prerequisites](ble-demo.md#ble-demo-prereqs) and [Amazon FreeRTOS BLE Mobile SDK Demo Application](ble-demo.md#ble-sdk-app)\. + +## iOS SDK for Amazon FreeRTOS Bluetooth Devices + +Use the iOS SDK for Amazon FreeRTOS Bluetooth Devices to build iOS mobile applications that interact with your microcontroller over BLE\. The SDK is available on [GitHub](https://github.com/aws/amazon-freertos-ble-ios-sdk/)\. + +**To install the iOS SDK** + +1. Install [CocoaPods](http://cocoapods.org/): + + ``` + $ gem install cocoapods + $ pod setup + ``` +**Note** +You might need to use `sudo` to install CocoaPods\. + +1. Install the SDK with CocoaPods: + + ``` + $ pod 'AmazonFreeRTOS', :git => 'https://github.com/aws/amazon-freertos-ble-ios-sdk.git' + ``` + +For information about setting up and running the demo mobile application that is included with the SDK, see [Prerequisites](ble-demo.md#ble-demo-prereqs) and [Amazon FreeRTOS BLE Mobile SDK Demo Application](ble-demo.md#ble-sdk-app)\. \ No newline at end of file diff --git a/doc_source/freertos-dev-guide.md b/doc_source/freertos-dev-guide.md index b05a880..bd4dc22 100755 --- a/doc_source/freertos-dev-guide.md +++ b/doc_source/freertos-dev-guide.md @@ -7,4 +7,5 @@ This section contains information required for writing embedded applications wit + [FreeRTOS Kernel Fundamentals](dev-guide-freertos-kernel.md) + [Amazon FreeRTOS Libraries](dev-guide-freertos-libraries.md) + [Amazon FreeRTOS Over\-the\-Air Updates](freertos-ota-dev.md) -+ [Amazon FreeRTOS Console User Guide](freertos-ocw-ug.md) \ No newline at end of file ++ [Amazon FreeRTOS Console](freertos-ocw-ug.md) ++ [Troubleshooting Amazon FreeRTOS](troubleshooting_overview-afr.md) \ No newline at end of file diff --git a/doc_source/freertos-getting-started.md b/doc_source/freertos-getting-started.md index aa69f49..3442922 100755 --- a/doc_source/freertos-getting-started.md +++ b/doc_source/freertos-getting-started.md @@ -1,3 +1,17 @@ # Getting Started with Amazon FreeRTOS -This section shows you how to download and configure Amazon FreeRTOS and run a demo application on one of the qualified microcontroller boards\. In this tutorial, we assume you are familiar with AWS IoT and the AWS IoT console\. If not, we recommend that you start with the [AWS IoT Getting Started](http://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html) tutorial\. \ No newline at end of file +This section shows you how to download and configure Amazon FreeRTOS and run a demo application on one of the qualified microcontroller boards\. In this tutorial, we assume you are familiar with AWS IoT and the AWS IoT console\. If not, we recommend that you start with the [AWS IoT Getting Started](http://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html) tutorial\. + +**Topics** ++ [Prerequisites](freertos-prereqs.md) ++ [Getting Started with the Texas Instruments CC3220SF\-LAUNCHXL](getting_started_ti.md) ++ [Getting Started with the STMicroelectronics STM32L4 Discovery Kit IoT Node](getting_started_st.md) ++ [Getting Started with the NXP LPC54018 IoT Module](getting_started_nxp.md) ++ [Getting Started with the Microchip Curiosity PIC32MZEF](getting_started_mch.md) ++ [Getting Started with the Espressif ESP32\-DevKitC and the ESP\-WROVER\-KIT](getting_started_espressif.md) ++ [Getting Started with the Infineon XMC4800 IoT Connectivity Kit](getting_started_infineon.md) ++ [Getting Started with the Xilinx Avnet MicroZed Industrial IoT Kit](getting_started_xilinx.md) ++ [Getting Started with the Renesas Starter Kit\+ for RX65N\-2MB](getting_started_renesas.md) ++ [Getting Started with the MediaTek MT7697Hx Development Kit](getting_started_mediatek.md) ++ [Getting Started with the FreeRTOS Windows Simulator](getting_started_windows.md) ++ [Getting Started with the Nordic nRF52840\-DK](getting_started_nordic.md) \ No newline at end of file diff --git a/doc_source/freertos-lib-cloud-mqtt.md b/doc_source/freertos-lib-cloud-mqtt.md index 21669e1..56cf97f 100755 --- a/doc_source/freertos-lib-cloud-mqtt.md +++ b/doc_source/freertos-lib-cloud-mqtt.md @@ -37,22 +37,22 @@ MQTT task wakeup wakes up whenever the user calls an API to perform any operatio ``` Amazon FreeRTOS | - +-lib + + - lib | - +-mqtt - | +-aws_mqtt_lib.c [Required to use the MQTT library and the MQTT agent] - | +-aws_mqtt_agent.c [Required to use the MQTT agent] + + - mqtt + | + - aws_mqtt_lib.c [Required to use the MQTT library and the MQTT agent] + | + - aws_mqtt_agent.c [Required to use the MQTT agent] | - +-include + + - include | - +-private [For internal library use only!] - | +-aws_doubly_linked_list.h - | +-aws_mqtt_agent_config_defaults.h - | +-aws_mqtt_buffer.h - | +-aws_mqtt_config_defaults.h + + - private [For internal library use only!] + | + - aws_doubly_linked_list.h + | +- aws_mqtt_agent_config_defaults.h + | + - aws_mqtt_buffer.h + | + - aws_mqtt_config_defaults.h | - +-aws_mqtt_agent.h [Include to use the MQTT agent API] - +-aws_mqtt_lib.h [Include to use the MQTT library API] + + - aws_mqtt_agent.h [Include to use the MQTT agent API] + + - aws_mqtt_lib.h [Include to use the MQTT library API] ``` ## Major Configurations @@ -93,29 +93,29 @@ You should set these constants to the minimum values possible\. ### Requirements and Usage Restrictions -#### +#### The MQTT agent task is created using the xTaskCreateStatic\(\) API function \- so the task's stack and control block are statically allocated at compile time\. That ensures the MQTT agent can be used in applications that do not allow dynamic memory allocation, but does mean there is a dependency on configSUPPORT\_STATIC\_ALLOCATION being set to 1 in FreeRTOSConfig\.h\. -#### +#### he MQTT agent uses the FreeRTOS direct to task notification feature\. Calling an MQTT agent API function may change the calling task's notification value and state\. -#### +#### MQTT packets are stored in buffers provided by the Buffer Pool module\. It is highly recommended to ensure the number of buffers in the pool is at least double the number of MQTT transactions that will be in progress at any one time\. ## Developer Support -### `mqttconfigASSERT` +### `mqttconfigASSERT` mqttconfigASSERT\(\) is equivalent to, and used in exactly the same way as, the FreeRTOS configASSERT\(\) macro\. If you want assert statements in the MQTT agent then define mqttconfigASSERT\(\)\. If you do not want assert statements in the MQTT agent then leave mqttconfigASSERT\(\) undefined\. If you define mqttconfigASSERT\(\) to call the FreeRTOS configASSERT\(\), as shown below, then the MQTT agent will only include assert statements if the FreeRTOS configASSERT\(\) is defined\. `#define mqttconfigASSERT( x ) configASSERT( x )` -### `mqttconfigENABLE_DEBUG_LOGS` +### `mqttconfigENABLE_DEBUG_LOGS` -#### +#### Set `mqttconfigENABLE_DEBUG_LOGS` to **1** to print debug logs via calls to vLoggingPrintf\(\)\. diff --git a/doc_source/freertos-lib-cloud-shadows.md b/doc_source/freertos-lib-cloud-shadows.md index 754749c..2cad211 100755 --- a/doc_source/freertos-lib-cloud-shadows.md +++ b/doc_source/freertos-lib-cloud-shadows.md @@ -26,7 +26,7 @@ Your Wi\-Fi password\. The type of Wi\-Fi security used by your network\. `keyCLIENT_CERTIFICATE_PEM` -The certificate PEM associated with your IoT thing\. For more information, see [Configure Your Project](getting_started_ti.md#ti-freertos-config-project)\. +The certificate PEM associated with your IoT thing\. `keyCLIENT_PRIVATE_KEY_PEM` The private key PEM associated with your IoT thing\. For more information, see [Configure Your Project](getting_started_ti.md#ti-freertos-config-project)\. @@ -43,8 +43,8 @@ Amazon FreeRTOS + - lib | + - shadow - | + ─ aws_shadow.c - | + ─ aws_shadow_json.c + | + - aws_shadow.c + | + - aws_shadow_json.c + - include + - aws_shadow.h + - private diff --git a/doc_source/freertos-mds-projects-struct.md b/doc_source/freertos-mds-projects-struct.md index a339090..9224b37 100755 --- a/doc_source/freertos-mds-projects-struct.md +++ b/doc_source/freertos-mds-projects-struct.md @@ -12,46 +12,10 @@ There are two subfolders in the main Amazon FreeRTOS directory: The function `DEMO_RUNNER_RunDemos()` located in `AmazonFreeRTOS\demos\common\demo_runner\aws_demo_runner.c` contains code that calls each example\. By default, only the `vStartMQTTEchoDemo()` function is called\. Depending on the configuration you selected when you downloaded the code, or whether you obtained the code from GitHub, the other example runner functions are either commented out or omitted entirely\. Although you can change the selection of demos here, be aware that not all combinations of examples work together\. Depending on the combination, the software might not be able to be executed on the selected target due to memory constraints\. All of the examples that can be executed by Amazon FreeRTOS appear in the common directory under `demos`\. + `lib` - The `lib` directory contains the source code of the Amazon FreeRTOS libraries\. These libraries are available to you as part of Amazon FreeRTOS: - + MQTT - + Device shadow - + Greengrass - + Wi\-Fi + The `lib` directory contains the source code of the Amazon FreeRTOS libraries\. There are helper functions that assist in implementing the library functionality\. We do not recommend that you change these helper functions\. If you need to change one of these libraries, make sure it conforms to the library interface defined in the `libs/include` directory\. ## Configuration Files -The demos have been configured to get you started quickly\. You might want to change some of the configurations for your project to create a version that runs on your platform\. You can find configuration files at `AmazonFreeRTOS///common/config_files`\. - -The configuration files include: - -`aws_bufferpool.h` -Configures the size and quantity of static buffers available for use by the application\. - -`aws_clientcredential_keys.h` -Configures your device certificate and private key\. - -`aws_demo_config.h` -Configures the task parameters used in the demos: stack size, priorities, and so on\. - -`aws_ggd_config.h` -Configures the parameters used to configure a Greengrass core, such as network interface IDs\. - -`aws_mqtt_agent_config.h` -Configures the parameters related to MQTT operations, such as task priorities, MQTT brokers, and keep\-alive counts\. - -`aws_mqtt_library.h` -Configures MQTT library parameters, such as the subscription length and the maximum number of subscriptions\. - -`aws_secure_sockets_config.h` -Configures the timeouts and the byte ordering when using SSL\. - -`aws_shadow_configure.h` -Configures the parameters used for an AWS IoT shadow, such as the number of JSMN tokens used when parsing a JSON file received from a shadow\. - -`aws_clientcredential.h` -Configures parameters, including the Wi\-Fi \(SSID, password, and security type\), the MQTT broker endpoint, and IoT thing name\. - -`FreeRTOSConfig.h` -Configures the FreeRTOS kernel for multitasking operations\. \ No newline at end of file +The demos have been configured to get you started quickly\. You might want to change some of the configurations for your project to create a version that runs on your platform\. You can find configuration files at `demos///common/config_files`\. \ No newline at end of file diff --git a/doc_source/freertos-ocw-ug.md b/doc_source/freertos-ocw-ug.md index 41edcbb..b25d2aa 100755 --- a/doc_source/freertos-ocw-ug.md +++ b/doc_source/freertos-ocw-ug.md @@ -1,19 +1,19 @@ -# Amazon FreeRTOS Console User Guide - -## Managing Amazon FreeRTOS Configurations +# Amazon FreeRTOS Console You can use the [Amazon FreeRTOS console](https://console.aws.amazon.com/freertos) to manage software configurations and download Amazon FreeRTOS software for your device\. The Amazon FreeRTOS software is prequalified on a variety of platforms\. It includes the required hardware drivers, libraries, and example projects to help get you started quickly\. You can choose between predefined configurations or create custom configurations\. -### Predefined Amazon FreeRTOS Configurations +Make sure that you have completed the Getting Started with Amazon FreeRTOS [Prerequisites](https://docs.aws.amazon.com/iot/latest/userguide/freertos-prereqs.html)\. + +## Predefined Amazon FreeRTOS Configurations Predefined configurations are defined for the prequalified platforms: + TI CC3220SF\-LAUNCHXL + STM32 IoT Discovery Kit + NXP LPC54018 IoT Module + Microchip Curiosity PIC32MZEF -+ Espressif ESP32\-DevKitC -+ Espressif ESP3\-WROVER\-KIT + Infineon XMC4800 IoT Connectivity Kit ++ Renesas RSK\+ for RX65N\-2MB ++ MediaTek MT7697Hx Development Kit + Xilinx Avnet MicroZed Industrial IoT Starter Kit + FreeRTOS Windows Simulator @@ -35,7 +35,7 @@ You can also customize a predefined configuration if you want to change the Amaz 1. At the bottom of the page, choose **Create and download** to create and download the custom configuration\. -### Custom Amazon FreeRTOS Configurations +## Custom Amazon FreeRTOS Configurations Custom configurations allow you to specify your hardware platform, integrated development platform \(IDE\), compiler, and only those RTOS libraries you require\. This leaves more space on your devices for application code\. @@ -83,4 +83,8 @@ Do not use any personally identifiable information in your custom configuration 1. Under **Amazon FreeRTOS Device Software**, choose **Configure download**\. -1. Choose the ellipsis next to the configuration you want to delete, and then choose **Delete**\. \ No newline at end of file +1. Choose the ellipsis next to the configuration you want to delete, and then choose **Delete**\. + +## Quick Connect Workflow + +The Amazon FreeRTOS console also includes the Quick Connect workflow option for all boards with predefined configurations\. The Quick Connect workflow helps you configure and run Amazon FreeRTOS demo applications for AWS IoT and AWS IoT Greengrass\. To get started, choose the **Predefined configurations** tab, find your board, and then choose **Quick connect** and follow the Quick Connect workflow steps\. \ No newline at end of file diff --git a/doc_source/freertos-ota-dev.md b/doc_source/freertos-ota-dev.md index 2354bb9..94f8ed8 100755 --- a/doc_source/freertos-ota-dev.md +++ b/doc_source/freertos-ota-dev.md @@ -1,6 +1,6 @@ # Amazon FreeRTOS Over\-the\-Air Updates -Over\-the\-air \(OTA\) updates allow you to deploy files to one or more devices in your fleet\. Although OTA updates were designed to be used to update device firmware, you can use them to send any files to one or more devices registered with AWS IoT\. When you send files over the air, it is a best practice to digitally sign them so that the devices that receive the files can verify they have not been tampered with en route\. You can use [Code Signing for Amazon FreeRTOS](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html) to sign and encrypt your files or you can sign your files with your own code\-signing tools\. +Over\-the\-air \(OTA\) updates allow you to deploy files to one or more devices in your fleet\. Although OTA updates were designed to be used to update device firmware, you can use them to send any files to one or more devices registered with AWS IoT\. When you send files over the air, it is a best practice to digitally sign them so that the devices that receive the files can verify they have not been tampered with en route\. You can use [Code Signing for AWS IoT](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html) to sign and encrypt your files or you can sign your files with your own code\-signing tools\. When you create an OTA update, the [OTA Update Manager Service](ota-manager.md) creates an [AWS IoT job](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) to notify your devices that an update is available\. The OTA demo application runs on your device and creates an Amazon FreeRTOS task that subscribes to notification topics for AWS IoT jobs and listens for update messages\. When an update is available, the OTA agent publishes requests to AWS IoT streaming topics and receives file blocks using the MQTT protocol\. It reassembles the blocks into files and checks the digital signature of the downloaded files\. If the files are valid, it installs the firmware update\. If you are not using the Amazon FreeRTOS OTA Update demo application, you must integrate the [Amazon FreeRTOS Over\-the\-Air \(OTA\) Agent Library](ota-agent-library.md) into your own application to get the firmware update capability\. diff --git a/doc_source/freertos-prereqs.md b/doc_source/freertos-prereqs.md index 2b156a9..331e7db 100755 --- a/doc_source/freertos-prereqs.md +++ b/doc_source/freertos-prereqs.md @@ -45,29 +45,31 @@ For more information about policies, see [IAM Permissions and Policies](https:// ## Amazon FreeRTOS Supported Hardware Platforms You need one of the supported MCU boards: -+ [STMicroelectronicsSTM32L4 Discovery Kit IoT Node](http://www.st.com/en/evaluation-tools/b-l475e-iot01a.html) -+ [Texas Instruments CC3220SF\-LAUNCHXL](http://www.ti.com/tool/CC3220SF-LAUNCHXL) -+ [NXP LPC54018 IoT Module](https://www.nxp.com/products/processors-and-microcontrollers/arm-based-processors-and-mcus/lpc-cortex-m-mcus/lpc54000-series-cortex-m4-mcus/lpc54018-iot-module-for-the-lpc540xx-family-of-mcus:OM40007) -+ [Microchip Curiosity PIC32MZEF Bundle](http://www.microchip.com/developmenttools/productdetails.aspx?partno=dm320104) -+ [Espressif ESP32\-DevKitC](https://www.espressif.com/en/products/hardware/esp32-devkitc/overview) -+ [Espressif ESP\-WROVER\-KIT](https://www.espressif.com/en/products/hardware/esp-wrover-kit/overview) -+ [Infineon XMC4800 IoT Connectivity Kit](https://www.infineon.com/cms/en/product/evaluation-boards/kit_xmc48_iot_aws_wifi) -+ [Xilinx Avnet MicroZed Industrial IoT Kit](https://www.xilinx.com/products/boards-and-kits/1-8dyf-85.html) ++ [STMicroelectronicsSTM32L4 Discovery Kit IoT Node](https://devices.amazonaws.com/detail/a3G0L00000AANsWUAX/STM32L4-Discovery-Kit-IoT-Node) ++ [Texas Instruments CC3220SF\-LAUNCHXL](https://devices.amazonaws.com/detail/a3G0L00000AANtaUAH/SimpleLink-Wi-Fi®-CC3220SF-Wireless-Microcontroller-LaunchPad-Development-Kit) ++ [NXP LPC54018 IoT Module](https://devices.amazonaws.com/detail/a3G0L00000AANtAUAX/LPC54018-IoT-Solution) ++ [Microchip Curiosity PIC32MZEF Bundle](https://devices.amazonaws.com/detail/a3G0L00000AANscUAH/Curiosity-PIC32MZ-EF-Amazon-FreeRTOS-Bundle) ++ [Espressif ESP32\-DevKitC](https://devices.amazonaws.com/detail/a3G0L00000AANtjUAH/ESP32-DevKitC) ++ [Espressif ESP\-WROVER\-KIT](https://devices.amazonaws.com/detail/a3G0L00000AANtlUAH/ESP-WROVER-KIT) ++ [Infineon XMC4800 IoT Connectivity Kit](https://devices.amazonaws.com/detail/a3G0L00000AANsbUAH/XMC4800-IoT-Amazon-FreeRTOS-Connectivity-Kit-WiFi) ++ [Xilinx Avnet MicroZed Industrial IoT Kit](https://devices.amazonaws.com/detail/a3G0L00000AANtqUAH/MicroZed-IIoT-Bundle-with-Amazon-FreeRTOS) ++ [MediaTek MT7697Hx Development Kit](https://devices.amazonaws.com/detail/a3G0L00000AAOmPUAX/MT7697Hx-Development-Kit) ++ [Renesas RX65N RSK IoT Module](https://devices.amazonaws.com/detail/a3G0L00000AAOQxUAP/AE-CLOUD2-Global-LTE-IoT-Connectivity-Kit) + Microsoft Windows 7 or later, with at least a dual core and a hard\-wired Ethernet connection -+ [Nordic nRF52840\-DK \[BETA\]](https://www.nordicsemi.com/eng/Products/nRF52840-DK) ++ [Nordic nRF52840\-DK \[BETA\]](https://devices.amazonaws.com/detail/a3G0L00000AANtrUAH/nRF52840-Development-Kit) ## Registering Your MCU Board with AWS IoT You must register your MCU board so it can communicate with AWS IoT\. To register your device, you must create: ++ An AWS IoT policy\. + + The AWS IoT policy grants your device permissions to access AWS IoT resources\. + An IoT thing\. An IoT thing allows you to manage your devices in AWS IoT\. + A private key and X\.509 certificate\. The private key and certificate allow your device to authenticate with AWS IoT\. -+ An AWS IoT policy\. - - The AWS IoT policy grants your device permissions to access AWS IoT resources\. **To create an AWS IoT policy** @@ -161,18 +163,39 @@ Grants your device the permission to receive messages from the AWS IoT message b 1. Choose the policy you just created and choose **Register thing**\. -## Install a Terminal Emulator +## Installing a Terminal Emulator + +A terminal emulator can help you diagnose problems or verify that your device code is running properly\. There are a variety of terminal emulators available for Windows, macOS, and Linux\. -A terminal emulator can help you diagnose problems or verify your device code is running properly\. There are a variety of terminal emulators available for Windows, macOS, and Linux\. You must connect your device to your computer before you attempt to connect a terminal emulator to your device\. +You must connect your board to your computer before you attempt to establish a serial connection to your board with a terminal emulator\. - Use these settings in your terminal emulator: +Use the following settings to configure your terminal emulator: | Terminal Setting | Value | | --- | --- | -| Port | Depends on platform and other devices you have connected to your computer\. | | BAUD rate | 115200 | | Data | 8 bit | | Parity | none | | Stop | 1 bit | -| Flow control | none | \ No newline at end of file +| Flow control | none | + +If you do not know your board's serial port, you can issue one of the following commands from the command line or terminal to return the serial ports for all devices connected to your host computer: + +Windows + +``` +chgport +``` + +Linux + +``` +ls /dev/tty* +``` + +macOS + +``` +ls /dev/cu.* +``` \ No newline at end of file diff --git a/doc_source/freertos-qualification-program.md b/doc_source/freertos-qualification-program.md new file mode 100755 index 0000000..323cb87 --- /dev/null +++ b/doc_source/freertos-qualification-program.md @@ -0,0 +1,3 @@ +# Amazon FreeRTOS Qualification Program + +The Amazon FreeRTOS Qualification Program is now a part of the AWS Device Qualification Program\. For more information about the AWS Device Qualification Program, visit the [AWS Partner Network website](https://aws.amazon.com/partners/dqp/)\. \ No newline at end of file diff --git a/doc_source/freertos-wifi.md b/doc_source/freertos-wifi.md index 8b13c52..ebf2704 100755 --- a/doc_source/freertos-wifi.md +++ b/doc_source/freertos-wifi.md @@ -124,7 +124,7 @@ For a full API reference, see [Wi\-Fi API Reference](https://docs.aws.amazon.com ## Example Usage -### Connecting to a Known AP +### Connecting to a Known AP ``` #define clientcredentialWIFI_SSID "MyNetwork" @@ -168,7 +168,7 @@ else } ``` -### Scanning for nearby APs +### Scanning for nearby APs ``` WIFINetworkParams_t xNetworkParams; diff --git a/doc_source/getting_started_espressif.md b/doc_source/getting_started_espressif.md index 3f37c4f..cd036d4 100755 --- a/doc_source/getting_started_espressif.md +++ b/doc_source/getting_started_espressif.md @@ -1,6 +1,6 @@ # Getting Started with the Espressif ESP32\-DevKitC and the ESP\-WROVER\-KIT -Both the [ESP32\-DevKitC](https://www.espressif.com/en/products/hardware/esp32-devkitc/overview) and the [ESP\-WROVER KIT](https://www.espressif.com/en/products/hardware/esp-wrover-kit/overview) are supported on Amazon FreeRTOS\. To check which development module you have, see [ESP32 Modules and Boards](https://docs.espressif.com/projects/esp-idf/en/latest/hw-reference/modules-and-boards.html)\. +If you don't have an Espressif ESP32\-DevKitC, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANtjUAH/ESP32-DevKitC)\. If you don't have an Espressif ESP32=WROVER\-KIT, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANtlUAH/ESP-WROVER-KIT)\. Both devices are supported on Amazon FreeRTOS\. To check which development module you have, see [ESP32 Modules and Boards](https://docs.espressif.com/projects/esp-idf/en/latest/hw-reference/modules-and-boards.html)\. **Note** Currently, the Amazon FreeRTOS port for ESP32\-WROVER\-KIT and ESP DevKitC does not support the following: @@ -36,11 +36,12 @@ After your environment is set up, you can download Amazon FreeRTOS\. ### Downloading Amazon FreeRTOS -Clone the Amazon FreeRTOS repository from [GitHub](https://github.com/aws/amazon-freertos)\. +Clone the `amazon-freertos` repository from [GitHub](https://github.com/aws/amazon-freertos)\. + +In this tutorial, the path to the `amazon-freertos` directory is referred to as `BASE_FOLDER`\. **Note** -The maximum length of a file path on Microsoft Windows is 260 characters\. The longest path in the Amazon FreeRTOS download is 122 characters\. To accommodate the files in the Amazon FreeRTOS projects, make sure that the path to the `AmazonFreeRTOS` directory is fewer than 98 characters long\. For example, `C:\Users\Username\Dev\AmazonFreeRTOS` works, but `C:\Users\Username\Documents\Development\Projects\AmazonFreeRTOS` causes build failures\. -In this tutorial, the path to the `AmazonFreeRTOS` directory is referred to as `BASE_FOLDER`\. +The maximum length of a file path on Microsoft Windows is 260 characters\. The longest path in the Amazon FreeRTOS download is 122 characters\. To accommodate the files in the Amazon FreeRTOS projects, make sure that the path to the `amazon-freertos` directory is fewer than 98 characters long\. For example, `C:\Users\Username\Dev\amazon-freertos` works, but `C:\Users\Username\Documents\Development\Projects\amazon-freertos` causes build failures\. ### Configure Your Project @@ -61,7 +62,7 @@ In this tutorial, the path to the `AmazonFreeRTOS` directory is referred to as ` Amazon FreeRTOS includes scripts to make it easier to set up your Espressif board\. To configure the Espressif scripts, open `/tools/aws_config_quick_start/configure.json` and set the following attributes: `afr_source_dir` -The complete path to the Amazon FreeRTOS download on your computer\. +The complete path to the `amazon-freertos` directory on your computer\. Make sure that you use forward slashes to specify this path\. `thing_name` The name of the IoT thing that represents your board\. @@ -90,7 +91,7 @@ Valid security types are: This script creates an IoT thing, certificate, and policy\. It attaches the IoT policy to the certificate and the certificate to the IoT thing\. It also populates the `aws_clientcredential.h` file with your AWS IoT endpoint, Wi\-Fi SSID, and credentials\. Finally, it formats your certificate and private key and writes them to the `aws_clientcredential.h` header file\. For more information about the script, see the README\.md in the `/tools/aws_config_quick_start` directory\. -## Build and Run Amazon FreeRTOS Samples +## Build and Run the Amazon FreeRTOS Demo Project **To flash the demo application onto your board** @@ -104,15 +105,13 @@ This script creates an IoT thing, certificate, and policy\. It attaches the IoT make menuconfig ``` - In the Espressif IoT Development Framework Configuration menu, navigate to **Serial flasher config**, and then to **Default serial port** to configure the serial port\. - - On Windows, serial ports have names like `COM1`\. On macOS, they start with `/dev/cu`\. On Linux, they start with `/dev/tty`\. + In the Espressif IoT Development Framework Configuration menu, navigate to **Serial flasher config**\. - The serial port you configure here is used to write the demo application to your board\. + To confirm a selection in the menu, choose **Select**\. To save a configuration, choose **Save**\. To exit the Espressif IoT Development Framework Configuration menu, choose **Exit**\. - Depending on your hardware, you can increase the default baud rate up to 921600\. This can reduce the time required to flash your board\. To increase the baud rate, choose **Serial flash config**, and then choose **Default baud rate**\. + Choose **Default serial port** to configure the serial port\. The serial port you configure here is used to write the demo application to your board\. On Windows, serial ports have names like `COM1`\. On macOS, they start with `/dev/cu`\. On Linux, they start with `/dev/tty`\. - To confirm your selection, choose ENTER\. To save the configuration, choose **Save** and then choose **Exit**\. + Choose **Default baud rate** to change the default baud rate to use while communicating with your board\. Increasing the baud rate can reduce the time required to flash your board\. Depending on your hardware, you can increase the default baud rate up to 921600\. To build and flash firmware \(including boot loader and partition table\) and monitor serial console output, open a command prompt\. Navigate to `\demos\espressif\esp32_devkitc_esp_wrover_kit/make` and run the following command: @@ -295,7 +294,15 @@ I (20956) PKCS11: Partition size: total: 52961, used: 0 | --- | | Amazon FreeRTOS support for Bluetooth Low Energy is in public beta release\. BLE demos are subject to change\. | -Amazon FreeRTOS supports [Bluetooth Low Energy \(BLE\)](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-ble-library.html) connectivity\. You can download Amazon FreeRTOS with BLE from [GitHub](https://github.com/aws/amazon-freertos/tree/feature/ble-beta)\. +Amazon FreeRTOS supports [Bluetooth Low Energy \(BLE\)](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-ble-library.html) connectivity\. You can download Amazon FreeRTOS with BLE from [GitHub](https://github.com/aws/amazon-freertos/tree/feature/ble-beta)\. The Amazon FreeRTOS BLE library is still in public beta, so you need to switch branches to access the code for your board\. Check out the branch named `feature/ble-beta`\. + +To run the Amazon FreeRTOS demo project across BLE, you need to run the Amazon FreeRTOS BLE Mobile SDK Demo Application on an iOS or Android mobile device\. + +**To set up the the Amazon FreeRTOS BLE Mobile SDK Demo Application** + +1. Follow the instructions in [Mobile SDKs for Amazon FreeRTOS Bluetooth Devices](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-ble-mobile.html) to download and install the SDK for your mobile platform on your host computer\. + +1. Follow the instructions in [Amazon FreeRTOS BLE Mobile SDK Demo Application](https://docs.aws.amazon.com/freertos/latest/userguide/ble-demo.html#ble-sdk-app) to set up the demo mobile application on your mobile device\. For instructions about how to run the MQTT over BLE demo on your board, see the [MQTT over BLE demo application](https://docs.aws.amazon.com/freertos/latest/userguide/ble-demo.html#ble-demo-mqtt)\. @@ -315,7 +322,7 @@ For instructions about how to run the Wi\-Fi Provisioning demo on your board, se + If you see errors when you run `idf_monitor.py`, use Python 2\.7\. **Other Notes** -+ Required libraries from ESP\-IDF are included in Amazon FreeRTOS , so there is no need to download them externally\. If `IDF_PATH` is set, we recommend that you remove it before you build Amazon FreeRTOS\. ++ Required libraries from ESP\-IDF are included in Amazon FreeRTOS, so there is no need to download them externally\. If the `IDF_PATH` environment variable is set, we recommend that you clear it before you build Amazon FreeRTOS\. + On Window systems, it can take 3\-4 minutes for the project to build\. You can use the `-j4` switch on the make command to reduce the build time: ``` @@ -437,22 +444,18 @@ The ESP32 supports a maximum of two break points\. The output from `system_profiler` should look like the following: ``` - C232HM-DDHSL-0: - Product ID: 0x6014 - Vendor ID: 0x0403 (Future Technology Devices International Limited) + DEVICE: + + Product ID: product-ID + Vendor ID: vendor-ID (Future Technology Devices International Limited) ``` -1. Verify the vendor and product IDs match the IDs in `demos/espressif/esp32_devkitc_esp_wrover_kit/esp32_devkitj_v1.cfg`\. The IDs are specified on a line that begins with `ftdi_vid_pid` followed by a vendor ID and a product ID: - - ``` - ftdi_vid_pid 0x0403 0x6014 - ``` +1. Open `demos/espressif/esp32_devkitc_esp_wrover_kit/esp32_devkitj_v1.cfg`\. The vendor ID and product ID for your device are specified in a line that begins with `ftdi_vid_pid`\. Change the IDs to match the IDs from the `system_profiler` output in the previous step\. 1. Open a terminal window, navigate to `/demos/espressif/esp32_devkitc_esp_wrover_kit/make`, and use the following command to run OpenOCD: ``` - openocd -f esp32_devkitj_v1.cfg -f - esp-wroom-32.cfg + openocd -f esp32_devkitj_v1.cfg -f esp-wroom-32.cfg ``` 1. Open a new terminal, and use the following command to load the FTDI serial port driver: diff --git a/doc_source/getting_started_infineon.md b/doc_source/getting_started_infineon.md index ae693e7..c4339a1 100755 --- a/doc_source/getting_started_infineon.md +++ b/doc_source/getting_started_infineon.md @@ -2,7 +2,7 @@ Before you begin, see [Prerequisites](freertos-prereqs.md)\. -If you do not have the Infineon XMC4800 IoT Connectivity Kit, you can purchase one from [Infineon](https://www.infineon.com/cms/en/product/evaluation-boards/kit_xmc48_iot_aws_wifi/)\. +If you do not have the Infineon XMC4800 IoT Connectivity Kit, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANsbUAH/XMC4800-IoT-Amazon-FreeRTOS-Connectivity-Kit-WiFi)\. If you want to open a serial connection with the board to view logging and debugging information, you need a 3\.3V USB/Serial converter, in addition to the XMC4800 IoT Connectivity Kit\. The CP2104 is a common USB/Serial converter that is widely available in boards such as Adafruit's [CP2104 Friend](https://www.adafruit.com/product/3309)\. @@ -69,7 +69,7 @@ In this tutorial, the path to the `AmazonFreeRTOS` directory is referred to as ` ### Configure Your Project -To run the demo, you must configure your project to work with AWS IoT\. To configure your project to work with AWS IoT, your board must be registered as an AWS IoT thing\. [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) is a step in the [Prerequisites](freertos-prereqs.md)\. +To run the demo, you must configure your project to work with AWS IoT, which requires that you register your board as an AWS IoT thing\. [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) is a step in the [Prerequisites](freertos-prereqs.md)\. **To configure your AWS IoT endpoint** @@ -87,7 +87,7 @@ To run the demo, you must configure your project to work with AWS IoT\. To confi + `clientcredentialMQTT_BROKER_ENDPOINT` *Your AWS IoT endpoint* + `clientcredentialIOT_THING_NAME` *The AWS IoT thing name of your board* -**To configure your Wi\-Fi** +**To configure your Wi\-Fi settings** 1. Open the `aws_clientcredential.h` file\. @@ -118,9 +118,9 @@ Amazon FreeRTOS is a C language project, and the certificate and private key mus **Note** The certificate and private key are hard\-coded for demonstration purposes only\. Production\-level applications should store these files in a secure location\. -## Build and Run Amazon FreeRTOS Samples +## Build and Run the Amazon FreeRTOS Demo Project -### Import the Amazon FreeRTOS Sample Code into DAVE +### Import the Amazon FreeRTOS Demo into DAVE 1. Start DAVE\. @@ -142,7 +142,7 @@ The certificate and private key are hard\-coded for demonstration purposes only\ Make sure that the project builds without errors\. -### Run the FreeRTOS Demo +### Run the Amazon FreeRTOS Demo Project After you have configured your project, you are ready to run the demo project on your board\. diff --git a/doc_source/getting_started_mch.md b/doc_source/getting_started_mch.md index 0df48f9..ffb9a94 100755 --- a/doc_source/getting_started_mch.md +++ b/doc_source/getting_started_mch.md @@ -2,7 +2,7 @@ Before you begin, see [Prerequisites](freertos-prereqs.md)\. -If you do not have the Microchip Curiosity PIC32MZEF bundle, you can purchase one from [Microchip](http://www.microchipdirect.com/product/search/all/dm320104-BNDL)\. You need the following items: +If you do not have the Microchip Curiosity PIC32MZEF bundle, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANscUAH/Curiosity-PIC32MZ-EF-Amazon-FreeRTOS-Bundle)\. You need the following items: + [MikroElectronika USB UART Click Board](https://www.mikroe.com/usb-uart-click) + [RJ\-11 to ICSP Adapter](https://www.microchipdirect.com/product/search/all/ac164110) + [MPLAB ICD 4 In\-Circuit Debugger](http://www.microchip.com/Developmenttools/ProductDetails.aspx?PartNO=DV164045) @@ -87,7 +87,7 @@ In this tutorial, the path to the `AmazonFreeRTOS` directory is referred to as ` ### Configure Your Project -To run the demo, you must configure your project to work with AWS IoT\. To configure your project to work with AWS IoT, your board must be registered as an AWS IoT thing\. [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) is a step in the [Prerequisites](freertos-prereqs.md)\. +To run the demo, you must configure your project to work with AWS IoT, which requires that you register your board as an AWS IoT thing\. [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) is a step in the [Prerequisites](freertos-prereqs.md)\. **To configure your AWS IoT endpoint** @@ -105,7 +105,7 @@ To run the demo, you must configure your project to work with AWS IoT\. To confi + `clientcredentialMQTT_BROKER_ENDPOINT` *Your AWS IoT endpoint* + `clientcredentialIOT_THING_NAME` *The AWS IoT thing name of your board* -**To configure your Wi\-Fi** +**To configure your Wi\-Fi settings** 1. Open the `aws_clientcredential.h` file\. @@ -136,9 +136,9 @@ Amazon FreeRTOS is a C language project, and the certificate and private key mus **Note** The certificate and private key are hard\-coded for demonstration purposes only\. Production\-level applications should store these files in a secure location\. -## Build and Run Amazon FreeRTOS Samples +## Build and Run Amazon FreeRTOS Demo Project -### Open the Amazon FreeRTOS Demo Application in the MPLAB IDE +### Open the Amazon FreeRTOS Demo in the MPLAB IDE 1. In the MPLAB IDE, from the **File** menu, choose **Open Project**\. @@ -154,7 +154,7 @@ warning: Configuration "pic32mz_ef_curiosity" builds with "XC32", but indicates warning: Configuration "pic32mz_ef_curiosity" refers to file "AmazonFreeRTOS/lib/third_party/mcu_vendor/microchip/harmony/framework/bootloader/src/bootloader.h" which does not exist in the disk. The make process might not build correctly. ``` -### Run the Amazon FreeRTOS Samples +### Run the Amazon FreeRTOS Demo Project 1. Rebuild your project\. diff --git a/doc_source/getting_started_mediatek.md b/doc_source/getting_started_mediatek.md new file mode 100755 index 0000000..07172c0 --- /dev/null +++ b/doc_source/getting_started_mediatek.md @@ -0,0 +1,175 @@ +# Getting Started with the MediaTek MT7697Hx Development Kit + +Before you begin, see [Prerequisites](freertos-prereqs.md)\. + +If you do not have the MediaTek MT7697Hx Development Kit, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AAOmPUAX/MT7697Hx-Development-Kit)\. + +## Setting Up Your Environment + +Before you set up your environment, connect your computer to the USB port on the MediaTek MT7697Hx Development Kit\. + +### Download and Install Keil MDK + +You can use the GUI\-based Keil Microcontroller Development Kit \(MDK\) to configure, build, and run Amazon FreeRTOS projects on your board\. Keil MDK includes the μVision IDE and the μVision Debugger\. + +**Note** +Keil MDK is supported on Windows 7, Windows 8, and Windows 10 64\-bit machines only\. + +**To download and install Keil MDK** + +1. Go to the [Keil MDK Getting Started](http://www2.keil.com/mdk5/install/) page, and choose **Download MDK\-Core**\. + +1. Enter and submit your information to register with Keil\. + +1. Right\-click the MDK executable and save the Keil MDK installer to your computer\. + +1. Open the Keil MDK installer and follow the steps to completion\. Make sure that you install the MediaTek device pack \(MT76x7 Series\)\. + +### Set Up a Serial Connection + +To establish a serial connection with the MediaTek MT7697Hx Development Kit, you must install the Arm Mbed Windows serial port driver\. You can download the driver from [Mbed](https://os.mbed.com/docs/latest/tutorials/windows-serial-driver.html)\. Follow the steps on the **Windows serial driver** page to download and install the driver for the MediaTek MT7697Hx Development Kit\. + +After you install the driver, a COM port appears in the Windows Device Manager\. For debugging, you can open a session to the port with a terminal utility tool such as HyperTerminal or TeraTerm\. + +## Download and Configure Amazon FreeRTOS + +After you set up your environment, you can download Amazon FreeRTOS\. + +### Download Amazon FreeRTOS + +**To download Amazon FreeRTOS** + +1. Browse to the AWS IoT console\. + +1. In the navigation pane, choose **Software**\. + +1. Under **Amazon FreeRTOS Device Software**, choose **Configure download**\. + +1. Under **Software Configurations**, find **Connect to AWS IoT \- MediaTek**, and then choose **Download**\. + +1. Unzip the downloaded file to a folder, and make a note of the folder path\. The unzipped folder is named `AmazonFreeRTOS`\. + +**Note** +The maximum length of a file path on Microsoft Windows is 260 characters\. The longest path in the Amazon FreeRTOS download is 122 characters\. To accommodate the files in the Amazon FreeRTOS projects, make sure that the path to the `AmazonFreeRTOS` directory is fewer than 98 characters long\. For example, `C:\Users\Username\Dev\AmazonFreeRTOS` works, but `C:\Users\Username\Documents\Development\Projects\AmazonFreeRTOS` causes build failures\. +In this tutorial, the path to the `AmazonFreeRTOS` directory is referred to as `BASE_FOLDER`\. + +### Configure Your Project + +To run the demo, you must configure your project to work with AWS IoT, which requires that you register your board as an AWS IoT thing\. [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) is a step in the [Prerequisites](freertos-prereqs.md)\. + +**To configure your AWS IoT endpoint** + +1. Browse to the [AWS IoT console](https://console.aws.amazon.com/iotv2/)\. + +1. In the navigation pane, choose **Settings**\. + + Your AWS IoT endpoint is displayed in **Endpoint**\. It should look like `<1234567890123>-ats.iot..amazonaws.com`\. Make a note of this endpoint\. + +1. In the navigation pane, choose **Manage**, and then choose **Things**\. + + Your device should have an AWS IoT thing name\. Make a note of this name\. + +1. In your IDE, open `\demos\common\include\aws_clientcredential.h` and specify values for the following `#define` constants: + + `clientcredentialMQTT_BROKER_ENDPOINT` *Your AWS IoT endpoint* + + `clientcredentialIOT_THING_NAME` *The AWS IoT thing name of your board* + +**To configure your Wi\-Fi settings** + +1. Open the `aws_clientcredential.h` file\. + +1. Specify values for the following `#define` constants: + + `clientcredentialWIFI_SSID` *The SSID for your Wi\-Fi network* + + `clientcredentialWIFI_PASSWORD` *The password for your Wi\-Fi network* + + `clientcredentialWIFI_SECURITY` *The security type of your Wi\-Fi network* + + Valid security types are: + + `eWiFiSecurityOpen` \(Open, no security\) + + `eWiFiSecurityWEP` \(WEP security\) + + `eWiFiSecurityWPA` \(WPA security\) + + `eWiFiSecurityWPA2` \(WPA2 security\) + +**To configure your AWS IoT credentials** +**Note** +To configure your AWS IoT credentials, you need the private key and certificate that you downloaded from the AWS IoT console when you registered your device\. After you have registered your device as an AWS IoT thing, you can retrieve device certificates from the AWS IoT console, but you cannot retrieve private keys\. + +Amazon FreeRTOS is a C language project, and the certificate and private key must be specially formatted to be added to the project\. You must format the certificate and private key for your device\. + +1. In a browser window, open `\tools\certificate_configuration\CertificateConfigurator.html`\. + +1. Under **Certificate PEM file**, choose the `-certificate.pem.crt` that you downloaded from the AWS IoT console\. + +1. Under **Private Key PEM file**, choose the `-private.pem.key` that you downloaded from the AWS IoT console\. + +1. Choose **Generate and save aws\_clientcredential\_keys\.h**, and then save the file in `\demos\common\include`\. This overwrites the existing file in the directory\. +**Note** +The certificate and private key are hard\-coded for demonstration purposes only\. Production\-level applications should store these files in a secure location\. + +## Build and Run the Amazon FreeRTOS Demo Project with Keil MDK + +**To build the Amazon FreeRTOS demo project in Keil μVision** + +1. From the **Start** menu, open Keil μVision 5\. + +1. Open the `/demos/mediatek/mt7697hx-dev-kit/uvision/aws_demo.uvprojx` project file\. + +1. From the menu, choose **Project**, and then choose **Build target**\. + + After the code is built, you see the demo executable file at `/demos/mediatek/mt7697hx-dev-kit/uvision/out/Objects/aws_demo.axf`\. + +**To run the Amazon FreeRTOS demo project** + +1. Set the MediaTek MT7697Hx Development Kit to PROGRAM mode\. + + To set the kit to PROGRAM mode, press and hold the **PROG** button\. With the **PROG** button still pressed, press and release the **RESET** button, and then release the **PROG** button\. + +1. From the menu, choose **Flash**, and then choose **Configure Flash Tools**\. + +1. In **Options for Target '`aws_demo`'**, choose the **Debug** tab\. Select **Use**, set the debugger to **CMSIS\-DAP Debugger**, and then choose **OK**\. + +1. From the menu, choose **Flash**, and then choose **Download**\. + + μVision notifies you when the download is complete\. + +1. Use a terminal utility to open the serial console window\. Set the serial port to 115200 bps, none\-parity, 8\-bits, and 1 stop\-bit\. + +1. Choose the **RESET** button on your MediaTek MT7697Hx Development Kit\. + +## Debugging Amazon FreeRTOS Projects in Keil μVision + +Currently, you must edit the MediaTek package that is included with Keil μVision before you can debug the Amazon FreeRTOS demo project for MediaTek with Keil μVision\. + +**To edit the MediaTek package for debugging Amazon FreeRTOS projects** + +1. Find and open the `Keil_v5\ARM\PACK\MediaTek\MTx\4.6.1\MediaTek.MTx.pdsc` file in your Keil MDK installation folder\. + +1. Replace all instances of `flag = Read32(0x20000000);` with `flag = Read32(0x0010FBFC);`\. + +1. Replace all instances of `Write32(0x20000000, 0x76877697);` with `Write32(0x0010FBFC, 0x76877697);`\. + +**To start debugging the project** + +1. From the menu, choose **Flash**, and then choose **Configure Flash Tools**\. + +1. Choose the **Target** tab, and then choose **Read/Write Memory Areas**\. Confirm that IRAM1 and IRAM2 are both selected\. + +1. Choose the **Debug** tab, and then choose **CMSIS\-DAP Debugger**\. + +1. Open `/demos/mediatek/mt7697hx-dev-kit/common/application_code/main.c`, and set the macro `MTK_DEBUGGER` to `1`\. + +1. Rebuild the demo project in μVision\. + +1. Set the MediaTek MT7697Hx Development Kit to PROGRAM mode\. + + To set the kit to PROGRAM mode, press and hold the **PROG** button\. With the **PROG** button still pressed, press and release the **RESET** button, and then release the **PROG** button\. + +1. From the μVision menu, choose **Debug**, and then choose **Start/Stop Debug Session**\. The **Call Stack \+ Locals** window opens when you start the debug session\. μVision flashes the demo to the board, runs the demo, and stops at the beginning of the `main()` function\. + +1. From the menu, choose **Debug**, and then choose **Stop** to stop the session\. The program counter stops at the following line: + + ``` + { volatile int wait_ice = 1 ; while ( wait_ice ) ; } + ``` + +1. In the **Call Stack \+ Locals** window, change the value for `wait_ice` to `0`\. + +1. Set breakpoints in your project's source code, and run the code\. \ No newline at end of file diff --git a/doc_source/getting_started_nordic.md b/doc_source/getting_started_nordic.md index 8cae8ea..4d53e69 100755 --- a/doc_source/getting_started_nordic.md +++ b/doc_source/getting_started_nordic.md @@ -7,7 +7,9 @@ Before you begin, see [Prerequisites](freertos-prereqs.md)\. -If you do not have the Nordic nRF52840\-DK, you can purchase one from [Nordic](https://www.nordicsemi.com/eng/Products/nRF52840-DK)\. +If you do not have the Nordic nRF52840\-DK, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANtrUAH/nRF52840-Development-Kit)\. + +To run the Amazon FreeRTOS BLE demo, you also need an iOS or Android mobile device with Bluetooth and Wi\-Fi capabilities\. ## Setting Up the Nordic Hardware @@ -21,23 +23,40 @@ For more information about setting up the Nordic nRF52840\-DK, see the [nRF52840 Amazon FreeRTOS supports Segger Embedded Studio as a development environment for the Nordic nRF52840\-DK\. -To set up your environment, you need to download and install Segger Embedded Studio\. +To set up your environment, you need to download and install Segger Embedded Studio on your host computer\. + +**To download and install Segger Embedded Studio** -1. Go to the [Segger Embedded Studio Downloads](https://www.segger.com/downloads/embedded-studio/) page and choose the Embedded Studio for ARM option for your operating system\. +1. Go to the [Segger Embedded Studio Downloads](https://www.segger.com/downloads/embedded-studio/) page, and choose the Embedded Studio for ARM option for your operating system\. 1. Run the installer and follow the prompts to completion\. +### Download the Mobile SDK for Amazon FreeRTOS Bluetooth Devices + +To run the Amazon FreeRTOS demo project across BLE, you need to run the Amazon FreeRTOS BLE Mobile SDK Demo Application on your mobile device\. + +**To set up the the Amazon FreeRTOS BLE Mobile SDK Demo Application** + +1. Follow the instructions in [Mobile SDKs for Amazon FreeRTOS Bluetooth Devices](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-ble-mobile.html) to download and install the SDK for your mobile platform on your host computer\. + +1. Follow the instructions in [Amazon FreeRTOS BLE Mobile SDK Demo Application](https://docs.aws.amazon.com/freertos/latest/userguide/ble-demo.html#ble-sdk-app) to set up the demo mobile application on your mobile device\. + ### Establish a Serial Connection -After you connect your computer to your Nordic nRF52840 board and install Segger Embedded Studio, open a terminal tool, like PuTTy, Tera Term, or GNU Screen\. Configure the terminal to connect to your board by a serial connection\. Set the COM port to **JLink CDC UART Port** with the following serial port settings: -+ Baud Rate: **115200** -+ Data: **8 bit** -+ Parity: **None** -+ Stop: **1 bit** -+ Flow Control: **None** +Segger Embedded Studio includes a terminal emulator that you can use to receive log messages across a serial connection to your board\. + +**To establish a serial connection with Segger Embedded Studio** + +1. Open Segger Embedded Studio\. + +1. From the top menu, choose **Target**, **Connect J\-Link**\. + +1. From the top menu, choose **Tools**, **Terminal Emulator**, **Properties**, and set the properties as instructed in [Installing a Terminal Emulator](freertos-prereqs.md#uart-term)\. + +1. From the top menu, choose **Tools**, **Terminal Emulator**, **Connect *port* \(115200,N,8,1\)**\. **Note** -Depending on your terminal tool, the serial port settings might vary in name\. +You can also establish a serial connection with a terminal tool of your choice, like PuTTy, Tera Term, or GNU Screen\. Configure the terminal to connect to your board by a serial connection as instructed in [Installing a Terminal Emulator](freertos-prereqs.md#uart-term)\. ## Download and Configure Amazon FreeRTOS @@ -69,41 +88,28 @@ To run the demo, you must configure your project to work with AWS IoT\. To confi + `clientcredentialMQTT_BROKER_ENDPOINT` *Your AWS IoT endpoint* + `clientcredentialIOT_THING_NAME` *Your board's AWS IoT thing name* -**To configure your AWS IoT credentials** - -To configure your AWS IoT credentials, you need the private key and certificate that you downloaded from the AWS IoT console when you registered your device as an AWS IoT thing\. After you have registered your device as an AWS IoT thing, you can retrieve device certificates from the AWS IoT console, but you cannot retrieve private keys\. - -Amazon FreeRTOS is a C language project, and the certificate and private key must be specially formatted to be added to the project\. You need to format the certificate and private key for your device\. - -1. In a browser window, open `\tools\certificate_configuration\CertificateConfigurator.html`\. - -1. Under **Certificate PEM file**, choose the `-certificate.pem.crt` that you downloaded from the AWS IoT console\. - -1. Under **Private Key PEM file**, choose the `-private.pem.key` that you downloaded from the AWS IoT console\. - -1. Choose **Generate and save aws\_clientcredential\_keys\.h**, and then save the file in `\demos\common\include`\. This overwrites the existing file in the directory\. -**Note** -The certificate and private key should be hard\-coded for demonstration purposes only\. Production\-level applications should store these files in a secure location\. - **To enable the demo** 1. Check that the BLE GATT Demo is enabled\. Go to `\demos\nordic\nrf52840-dk\common\config_files\aws_ble_config.h`, and make sure that `bleconfigENABLE_GATT_DEMO` is set to `1`\. -1. Open `\demos\common\demo_runner\aws_demo_runner.c`, and in the demo declarations, uncomment `extern void vStartMQTTBLEEchoDemo( void );`\. In the `DEMO_RUNNER_RunDemos` definition, uncomment `vStartMQTTBLEEchoDemo();`\. \. +1. Open `\demos\common\demo_runner\aws_demo_runner.c`, and in the demo declarations, uncomment `extern void vStartMQTTBLEEchoDemo( void );`\. In the `DEMO_RUNNER_RunDemos` definition, uncomment `vStartMQTTBLEEchoDemo();`\. -## Build and Run Amazon FreeRTOS Samples +## Build and Run the Amazon FreeRTOS Demo Project After you download Amazon FreeRTOS and configure your demo project, you are ready to build and run the demo project on your board\. -Open Segger Embedded Studio\. From the top menu, choose **File**, choose **Open Solution**, and then navigate to the project file `\demos\nordic\nrf52840-dk\ses\aws_demos_ble.emProject` +**To build and run the Amazon FreeRTOS BLE demo from Segger Embedded Studio** + +1. Open Segger Embedded Studio\. From the top menu, choose **File**, choose **Open Solution**, and then navigate to the project file `\demos\nordic\nrf52840-dk\ses\aws_demos_ble.emProject` -From the top menu, choose **View**, and then choose **Debug Terminal** to display information from your serial connection terminal\. +1. If you are using the Segger Embedded Studio terminal emulator, choose **Tools** from the top menu, and then choose **Terminal Emulator**, **Terminal Emulator** to display information from your serial connection\. -To build the BLE demo, right\-click the `aws_ble_demos` demo project, and choose **Build**\. + If you are using another terminal tool, you can monitor that tool for output from your serial connection\. +1. Right\-click the `aws_ble_demos` demo project in the **Project Explorer**, and choose **Build**\. **Note** If this is your first time using Segger Embedded Studio, you might see you a warning "No license for commercial use"\. Segger Embedded Studio can be used free of charge for Nordic Semiconductor devices\. Choose **Activate Your Free License**, and follow the instructions\. -To run the BLE demo on your board, from the Segger Embedded Studio menu, choose **Debug**, and then choose **Go**\. +1. Choose **Debug**, and then choose **Go**\. -For more information about completing the demo with the Amazon FreeRTOS BLE Mobile SDK demo application as the mobile MQTT proxy, see [MQTT over BLE Demo Application](https://docs.aws.amazon.com/freertos/latest/userguide/ble-demo.html#ble-demo-mqtt)\. \ No newline at end of file +1. Follow the instructions for the [MQTT over BLE Demo Application](https://docs.aws.amazon.com/freertos/latest/userguide/ble-demo.html#ble-demo-mqtt) to complete the demo with the Amazon FreeRTOS BLE Mobile SDK demo application as the mobile MQTT proxy\. \ No newline at end of file diff --git a/doc_source/getting_started_nxp.md b/doc_source/getting_started_nxp.md index 2930528..64ce904 100755 --- a/doc_source/getting_started_nxp.md +++ b/doc_source/getting_started_nxp.md @@ -2,7 +2,7 @@ Before you begin, see [Prerequisites](freertos-prereqs.md)\. -If you do not have an NXP LPC54018 IoT Module, you can order one from [NXP](https://www.nxp.com/products/processors-and-microcontrollers/arm-based-processors-and-mcus/lpc-cortex-m-mcus/lpc54000-series-cortex-m4-mcus/lpc54018-iot-module-for-the-lpc540xx-family-of-mcus:OM40007?fsrch=1&sr=1&pageNum=1)\. Use a USB cable to connect your NXP LPC54018 IoT Module to your computer\. +If you do not have an NXP LPC54018 IoT Module, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANtAUAX/LPC54018-IoT-Solution)\. Use a USB cable to connect your NXP LPC54018 IoT Module to your computer\. ## Setting Up Your Environment @@ -87,7 +87,7 @@ In this tutorial, the path to the `AmazonFreeRTOS` directory is referred to as ` ### Configure Your Project -To run the demo, you must configure your project to work with AWS IoT\. To configure your project to work with AWS IoT, your board must be registered as an AWS IoT thing\. [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) is a step in the [Prerequisites](freertos-prereqs.md)\. +To run the demo, you must configure your project to work with AWS IoT, which requires that you register your board as an AWS IoT thing\. [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) is a step in the [Prerequisites](freertos-prereqs.md)\. **To configure your AWS IoT endpoint** @@ -105,7 +105,7 @@ To run the demo, you must configure your project to work with AWS IoT\. To confi + `clientcredentialMQTT_BROKER_ENDPOINT` *Your AWS IoT endpoint* + `clientcredentialIOT_THING_NAME` *The AWS IoT thing name of your board* -**To configure your Wi\-Fi** +**To configure your Wi\-Fi settings** 1. Open the `aws_clientcredential.h` file\. @@ -136,9 +136,9 @@ Amazon FreeRTOS is a C language project, and the certificate and private key mus **Note** The certificate and private key are hard\-coded for demonstration purposes only\. Production\-level applications should store these files in a secure location\. -## Build and Run Amazon FreeRTOS Samples +## Build and Run the Amazon FreeRTOS Demo Project -### Import the Amazon FreeRTOS Sample Code into Your IDE +### Import the Amazon FreeRTOS Demo into Your IDE **To import the Amazon FreeRTOS sample code into the IAR Embedded Workbench IDE** @@ -156,7 +156,7 @@ The certificate and private key are hard\-coded for demonstration purposes only\ 1. From the **Project** menu, choose **Build All**\. -### Run the FreeRTOS Samples +### Run the Amazon FreeRTOS Demo Project To run the Amazon FreeRTOS demos on the NXP LPC54018 IoT Module board, connect the USB port on the NXP IoT Module to your host computer, open a terminal program, and connect to the port identified as USB Serial Device\. diff --git a/doc_source/getting_started_renesas.md b/doc_source/getting_started_renesas.md new file mode 100755 index 0000000..8e00fa9 --- /dev/null +++ b/doc_source/getting_started_renesas.md @@ -0,0 +1,190 @@ +# Getting Started with the Renesas Starter Kit\+ for RX65N\-2MB + +Before you begin, see [Prerequisites](freertos-prereqs.md)\. + +If you do not have the Renesas RSK\+ for RX65N\-2MB, visit the AWS Partner Device Catalog, and purchase one from our [partners](https://devices.amazonaws.com/detail/a3G0L00000AAOkeUAH/Renesas-Starter-Kit+-for-RX65N-2MB)\. + +## Setting Up the Renesas Hardware + +**To set up the RSK\+ for RX65N\-2MB** + +1. Connect your computer to the USB\-UART port on your RSK\+ for RX65N\-2MB\. + +1. Connect a router or internet\-connected Ethernet port to the Ethernet port on your RSK\+ for RX65N\-2MB\. + +**To set up the E2 Lite Debugger module** + +1. Use the 14\-pin ribbon cable to connect the E2 Lite Debugger module to the ‘E1/E2 Lite’ port on the RSK\+ for RX65N\-2MB\. + +1. Use a USB cable to connect the E2 Lite debugger module to your host machine\. When the E2 Lite debugger is connected to both the board and your computer, a green ‘ACT’ LED on the debugger flashes\. + +1. Connect the center positive \+5V power adapter to the PWR connector on the RSK\+ for RX65N\-2MB\. + +1. After the debugger is connected to your host machine and RSK\+ for RX65N\-2MB, the E2 Lite debugger drivers begin installing\. + + Note that administrator privileges are required to install the drivers\. + +## Setting Up Your Environment + +To set up Amazon FreeRTOS configurations for the RSK\+ for RX65N\-2MB, use the Renesas e2studio IDE and CC\-RX compiler\. + +**Note** +The Renesas e2studio IDE and CC\-RX compiler are only supported on Windows 7, 8, and 10 operating systems\. + +**To download and install e2studio** + +1. Go to the [Renesas e2studio installer](https://www.renesas.com/in/en/software/D4000820.html) download page, and download the offline installer\. + +1. You are directed to a Renesas Login page\. + + If you have an account with Renesas, enter your user name and password and then choose **Login**\. + + If you do not have an account, choose **Register now**, and follow the first registration steps\. You should receive an email with a link to activate your Renesas account\. Follow this link to complete your registration with Renesas, and then log in to Renesas\. + +1. After you log in, download the e2studio installer to your computer\. + +1. Open the installer and follow the steps to completion\. + +For more information, see the [e2studio](https://www.renesas.com/us/en/products/software-tools/tools/ide/e2studio.html#productInfo) on the Renesas website\. + +**To download and install the RX Family C/C\+\+ Compiler Package** + +1. Go to the [RX Family C/C\+\+ Compiler Package](https://www.renesas.com/us/en/software/D4000652.html) download page, and download the V2\.08 package\. + +1. Open the executable and install the compiler\. + +For more information, see the [C/C\+\+ Compiler Package for RX Family](https://www.renesas.com/us/en/products/software-tools/tools/compiler-assembler/compiler-package-for-rx-family.html#productInfo) on the Renesas website\. + +**Note** +The compiler is available free for evaluation version only and valid for 60 days\. On the 61st day, you need to get a License Key\. For more information, see [Evaluation Software Tools](https://www.renesas.com/us/en/products/software-tools/evaluation-software-tools.html)\. + +## Download and Configure Amazon FreeRTOS + +After you set up your environment, you can download Amazon FreeRTOS\. + +### Download Amazon FreeRTOS + +**To download Amazon FreeRTOS** + +1. Browse to the AWS IoT console\. + +1. In the navigation pane, choose **Software**\. + +1. Under **Amazon FreeRTOS Device Software**, choose **Configure download**\. + +1. Under **Software Configurations**, find **Connect to AWS IoT\- Renesas**, and then choose **Download**\. + +1. Unzip the downloaded file to the `AmazonFreeRTOS` folder, and make a note of the folder's path\. + +**Note** +The maximum length of a file path on Microsoft Windows is 260 characters\. The longest path in the Amazon FreeRTOS download is 122 characters\. To accommodate the files in the Amazon FreeRTOS projects, make sure that the path to the `AmazonFreeRTOS` directory is fewer than 98 characters long\. For example, `C:\Users\Username\Dev\AmazonFreeRTOS` works, but `C:\Users\Username\Documents\Development\Projects\AmazonFreeRTOS` causes build failures\. +In this tutorial, the path to the `AmazonFreeRTOS` directory is referred to as `BASE_FOLDER`\. + +### Configure Your Project + +To run the demo, you must configure your project to work with AWS IoT\. To configure your project to work with AWS IoT, your board must be registered as an AWS IoT thing\. This is a step in the [Prerequisites](freertos-prereqs.md)\. + +**To configure your AWS IoT endpoint** + +1. Browse to the [AWS IoT console](https://console.aws.amazon.com/iotv2/)\. + +1. In the navigation pane, choose **Settings**\. + + Your AWS IoT endpoint appears in the **Endpoint** text box\. It should look like `<1234567890123>-ats.iot..amazonaws.com`\. Make a note of this endpoint\. + +1. In the navigation pane, choose **Manage**, and then choose **Things**\. Make a note of the AWS IoT thing name for your device\. + +1. With your AWS IoT endpoint and your AWS IoT thing name on hand, open `\demos\common\include\aws_clientcredential.h` in your IDE, and specify values for the following `#define` constants: + + `clientcredentialMQTT_BROKER_ENDPOINT` *Your AWS IoT endpoint* + + `clientcredentialIOT_THING_NAME` *Your board's AWS IoT thing name* + +**To configure your AWS IoT credentials** + +To configure your AWS IoT credentials, you need the private key and certificate that you downloaded from the AWS IoT console when you registered your device as an AWS IoT thing\. After you have registered your device as an AWS IoT thing, you can retrieve device certificates from the AWS IoT console, but you cannot retrieve private keys\. + +Amazon FreeRTOS is a C language project, and the certificate and private key must be specially formatted to be added to the project\. You need to format the certificate and private key for your device\. + +1. In a browser window, open `\tools\certificate_configuration\CertificateConfigurator.html`\. + +1. Under **Certificate PEM file**, choose the `-certificate.pem.crt` that you downloaded from the AWS IoT console\. + +1. Under **Private Key PEM file**, choose the `-private.pem.key` that you downloaded from the AWS IoT console\. + +1. Choose **Generate and save aws\_clientcredential\_keys\.h**, and then save the file in `\demos\common\include`\. This overwrites the existing file in the directory\. +**Note** +The certificate and private key should be hard\-coded for demonstration purposes only\. Production\-level applications should store these files in a secure location\. + +## Build and Run Amazon FreeRTOS Samples + +Now that you have configured the demo project, you are ready to build and run the project on your board\. + +Before you run the demo project, use the MQTT client in the AWS IoT console to subscribe to the demo's MQTT topic\. + +**To subscribe to the MQTT topic** + +1. Sign in to the AWS IoT console\. + +1. In the navigation pane, choose **Test** to open the MQTT client\. + +1. In **Subscription topic**, enter **freertos/demos/echo**, and then choose **Subscribe to topic**\. + +### Build the Amazon FreeRTOS Demo in e2studio + +**To import and build the demo in e2studio** + +1. Launch e2studio from the Start menu\. + +1. On the **Select a directory as a workspace** window, browse to the folder that you want to work in, and choose **Launch**\. +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/e2studio1.png) + +1. The first time you open e2studio, the **Toolchain Registry** window opens\. Choose **Renesas Toolchains**, and confirm that **CC\-RX v2\.07\.00** is selected\. Choose **Register**, and then choose **OK**\. + +1. If you are opening e2studio for the first time, the **Code Generator Registration** window appears\. Choose **OK**\. + +1. The **Code Generator COM component register** window appears\. Under **Please restart e2studio to use Code Generator**, choose **OK**\. + +1. The **Restart e2studio** window appears\. Choose **OK**\. + +1. e2studio restarts\. On the **Select a directory as a workspace** window, choose **Launch**\. + +1. On the e2studio welcome screen, choose the **Go to the e2studio workbench** arrow icon\. + +1. Right\-click the **Project Explorer** window, and choose **Import**\. + +1. In the import wizard, choose **General**, **Existing Projects into Workspace**, and then choose **Next**\. +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/e2studio2.png) + +1. Choose **Browse**, locate the directory `\demos\renesas\rx65n-rsk\ccrx-e2studio`, and then choose **Finish**\. +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/e2studio3.png) + +1. From **Project** menu, choose **Project**, **Build All**\. + + The build console issues a warning message that the License Manager is not installed\. You can ignore this message unless you have a license key for the CC\-RX compiler\. To install the License Manager, see the [License Manager](https://www.renesas.com/us/en/software/D4000398.html) download page\. + +### Run the Amazon FreeRTOS Project + +**To run the project in e2studio** + +1. Confirm that you have connected the E2 Lite Debugger module to your RSK\+ for RX65N\-2MB + +1. From the top menu, choose **Run**, **Debug Configuration**\. + +1. Expand **Renesas GDB Hardware Debugging**, and choose **aws\_demos HardwareDebug**\. +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/e2studio4.png) + +1. Choose the **Debugger** tab, and then choose the **Connection Settings** tab\. Confirm that your connection settings are correct\. +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/e2studio5.png) + +1. Choose **Debug** to download the code to your board and begin debugging\. + + You might be prompted by a firewall warning for `e2-server-gdb.exe`\. Check **Private networks, such as my home or work network**, and then choose **Allow access**\. + +1. e2studio might ask to change to **Renesas Debug Perspective**\. Choose **Yes**\. + + The green 'ACT' LED on the E2 Lite Debugger illuminates\. + +1. After the code is downloaded to the board, choose **Resume** to run the code up to the first line of the main function\. Choose **Resume** again to run the rest of the code\. + + In the AWS IoT console's MQTT client, you see MQTT messages sent by your device\. + +For the latest projects released by Renesas, see the `renesas-rx` fork of the `amazon-freertos` repository on [GitHub](https://github.com/renesas-rx/amazon-freertos)\. \ No newline at end of file diff --git a/doc_source/getting_started_st.md b/doc_source/getting_started_st.md index 0db2b0c..b539f5c 100755 --- a/doc_source/getting_started_st.md +++ b/doc_source/getting_started_st.md @@ -2,7 +2,7 @@ Before you begin, see [Prerequisites](freertos-prereqs.md)\. -If you do not already have the STMicroelectronics STM32L4 Discovery Kit IoT Node, you can purchase one from [STMicroelectronics](http://www.st.com/en/evaluation-tools/b-l475e-iot01a.html)\. +If you do not already have the STMicroelectronics STM32L4 Discovery Kit IoT Node, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANsWUAX/STM32L4-Discovery-Kit-IoT-Node)\. Make sure you have installed the latest Wi\-Fi firmware\. To download the latest Wi\-Fi firmware, see [STM32L4 Discovery kit IoT node, low\-power wireless, BLE, NFC, SubGHz, Wi\-Fi](https://www.st.com/resource/en/utilities/inventek_fw_updater.zip)\. Under **Binary Resources**, choose **Inventek ISM 43362 Wi\-Fi module firmware update \(read the readme file for instructions\) **\. @@ -42,7 +42,7 @@ In this tutorial, the path to the `AmazonFreeRTOS` directory is referred to as ` ### Configure Your Project -To run the demo, you must configure your project to work with AWS IoT\. To configure your project to work with AWS IoT, your board must be registered as an AWS IoT thing\. [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) is a step in the [Prerequisites](freertos-prereqs.md)\. +To run the demo, you must configure your project to work with AWS IoT, which requires that you register your board as an AWS IoT thing\. [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) is a step in the [Prerequisites](freertos-prereqs.md)\. **To configure your AWS IoT endpoint** @@ -60,7 +60,7 @@ To run the demo, you must configure your project to work with AWS IoT\. To confi + `clientcredentialMQTT_BROKER_ENDPOINT` *Your AWS IoT endpoint* + `clientcredentialIOT_THING_NAME` *The AWS IoT thing name of your board* -**To configure your Wi\-Fi** +**To configure your Wi\-Fi settings** 1. Open the `aws_clientcredential.h` file\. @@ -91,9 +91,9 @@ Amazon FreeRTOS is a C language project, and the certificate and private key mus **Note** The certificate and private key are hard\-coded for demonstration purposes only\. Production\-level applications should store these files in a secure location\. -## Build and Run Amazon FreeRTOS Samples +## Build and Run the Amazon FreeRTOS Demo Project -### Import the Amazon FreeRTOS Sample Code into the STM32 System Workbench +### Import the Amazon FreeRTOS Demo into the STM32 System Workbench 1. Open the STM32 System Workbench and enter a name for a new workspace\. @@ -107,7 +107,7 @@ The certificate and private key are hard\-coded for demonstration purposes only\ 1. From the **Project** menu, choose **Build All**\. Confirm the project compiles without any errors or warnings\. -### Run the Amazon FreeRTOS Samples +### Run the Amazon FreeRTOS Demo Project 1. Use a USB cable to connect your STMicroelectronics STM32L4 Discovery Kit IoT Node to your computer\. @@ -147,9 +147,17 @@ You should see MQTT messages sent by your device in the MQTT client in the AWS I **Note** To run the BLE demo, you need the SPBTLE\-1S BLE module for the STM32L475 Discovery Kit\. -Amazon FreeRTOS supports [Bluetooth Low Energy \(BLE\)](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-ble-library.html) connectivity\. You can download Amazon FreeRTOS with BLE from [GitHub](https://github.com/aws/amazon-freertos/tree/feature/ble-beta)\. +Amazon FreeRTOS supports [Bluetooth Low Energy \(BLE\)](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-ble-library.html) connectivity\. You can download Amazon FreeRTOS with BLE from [GitHub](https://github.com/aws/amazon-freertos/tree/feature/ble-beta)\. The Amazon FreeRTOS BLE library is still in public beta, so you need to switch branches to access the code for your board\. Check out the branch named `feature/ble-beta`\. -For instructions about how to run the MQTT over BLE demo on your board, see the [MQTT over BLE demo application](https://docs.aws.amazon.com/freertos/latest/userguide/ble-demo.html#ble-demo-mqtt)\. +To run the Amazon FreeRTOS demo project across BLE, you need to run the Amazon FreeRTOS BLE Mobile SDK Demo Application on an iOS or Android mobile device\. + +**To set up the the Amazon FreeRTOS BLE Mobile SDK Demo Application** + +1. Follow the instructions in [Mobile SDKs for Amazon FreeRTOS Bluetooth Devices](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-ble-mobile.html) to download and install the SDK for your mobile platform on your host computer\. + +1. Follow the instructions in [Amazon FreeRTOS BLE Mobile SDK Demo Application](https://docs.aws.amazon.com/freertos/latest/userguide/ble-demo.html#ble-sdk-app) to set up the demo mobile application on your mobile device\. + + For instructions about how to run the MQTT over BLE demo on your board, see the [MQTT over BLE demo application](https://docs.aws.amazon.com/freertos/latest/userguide/ble-demo.html#ble-demo-mqtt)\. ## Troubleshooting diff --git a/doc_source/getting_started_ti.md b/doc_source/getting_started_ti.md index 6a8c533..3681617 100755 --- a/doc_source/getting_started_ti.md +++ b/doc_source/getting_started_ti.md @@ -2,7 +2,7 @@ Before you begin, see [Prerequisites](freertos-prereqs.md)\. -If you do not have the Texas Instruments \(TI\) CC3220SF\-LAUNCHXL Development Kit, you can purchase one from [Texas Instruments](http://www.ti.com/tool/CC3220SF-LAUNCHXL)\. +If you do not have the Texas Instruments \(TI\) CC3220SF\-LAUNCHXL Development Kit, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANtaUAH/SimpleLink-Wi-Fi®-CC3220SF-Wireless-Microcontroller-LaunchPad-Development-Kit)\. ## Setting Up Your Environment @@ -39,7 +39,7 @@ If you experience issues when you are installing Code Composer Studio, see [TI D ### Install the SimpleLink CC3220 SDK -Install the [SimpleLink CC3200 SDK](http://www.ti.com/tool/CC3200SDK)\. The SimpleLink Wi\-Fi CC3200 SDK contains drivers for the CC3200 programmable MCU, more than 40 sample applications, and documentation required to use the samples\. +Install the [SimpleLink CC3220 SDK](http://www.ti.com/tool/SIMPLELINK-CC3220-SDK)\. The SimpleLink Wi\-Fi CC3220 SDK contains drivers for the CC3220SF programmable MCU, more than 40 sample applications, and documentation required to use the samples\. ### Install Uniflash @@ -48,14 +48,14 @@ Install [Uniflash](http://www.ti.com/tool/UNIFLASH)\. CCS Uniflash is a standalo ### Configure Wi\-Fi Provisioning To configure the Wi\-Fi settings for your board, do one of the following: -+ Complete the Amazon FreeRTOS demo application described in [Configure Your Project](#ti-freertos-config-project)\. -+ Use [SmartConfig](http://processors.wiki.ti.com/index.php/CC3200_SmartConfig_Provisioning) from Texas Instruments\. ++ Configure the Amazon FreeRTOS demo application described in [Configure Your Project](#ti-freertos-config-project)\. ++ Use [SmartConfig](http://dev.ti.com/tirex/#/?link=Software%2FSimpleLink%20CC32xx%20SDK%2FSimpleLink%20Academy%2FWi-Fi%2FWi-Fi%20Provisioning) from Texas Instruments\. ### Install the Latest Service Pack 1. On your TI CC3220SF\-LAUNCHXL, place the SOP jumper on the middle set of pins \(position = 1\) and reset the board\. -1. Start Uniflash, and from the list of configurations, choose **CC3200SF\-LAUNCHXL**\. Choose **Start Image Creator**\. +1. Start Uniflash, and from the list of configurations, choose **CC3220SF\-LAUNCHXL**\. Choose **Start Image Creator**\. 1. Choose **New Project**\. @@ -87,7 +87,7 @@ After your environment is set up, you can download Amazon FreeRTOS\. If you are using IAR Embedded Workbench, choose **Connect to AWS IoT\-TI**\. Under **Hardware platform**, choose **Edit**\. Under **Integrated Development Environment \(IDE\)**, choose **IAR Embedded Workbench**\. Make sure the compiler is set to IAR, and then choose **Create and Download**\. -1. Unzip the downloaded file to your hard drive\. When unzipped, you have a directory named `AmazonFreeRTOS`\. You can place this directory anywhere you want, but be aware of path length limitations on Windows\. +1. Unzip the downloaded file to your hard drive\. When unzipped, you have a directory named `AmazonFreeRTOS`\. **Note** The maximum length of a file path on Microsoft Windows is 260 characters\. The longest path in the Amazon FreeRTOS download is 122 characters\. To accommodate the files in the Amazon FreeRTOS projects, make sure that the path to the `AmazonFreeRTOS` directory is fewer than 98 characters long\. For example, `C:\Users\Username\Dev\AmazonFreeRTOS` works, but `C:\Users\Username\Documents\Development\Projects\AmazonFreeRTOS` causes build failures\. @@ -95,7 +95,7 @@ In this tutorial, the path to the `AmazonFreeRTOS` directory is referred to as ` ### Configure Your Project -To run the demo, you must configure your project to work with AWS IoT\. To configure your project to work with AWS IoT, your board must be registered as an AWS IoT thing\. [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) is a step in the [Prerequisites](freertos-prereqs.md)\. +To run the demo, you must configure your project to work with AWS IoT, which requires that you register your board as an AWS IoT thing\. [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) is a step in the [Prerequisites](freertos-prereqs.md)\. **To configure your AWS IoT endpoint** @@ -113,7 +113,7 @@ To run the demo, you must configure your project to work with AWS IoT\. To confi + `clientcredentialMQTT_BROKER_ENDPOINT` *Your AWS IoT endpoint* + `clientcredentialIOT_THING_NAME` *The AWS IoT thing name of your board* -**To configure your Wi\-Fi** +**To configure your Wi\-Fi settings** 1. Open the `aws_clientcredential.h` file\. @@ -144,11 +144,11 @@ Amazon FreeRTOS is a C language project, and the certificate and private key mus **Note** The certificate and private key are hard\-coded for demonstration purposes only\. Production\-level applications should store these files in a secure location\. -## Build and Run Amazon FreeRTOS Samples +## Build and Run the Amazon FreeRTOS Demo Project -### Build and Run Amazon FreeRTOS Samples in TI Code Composer +### Build and Run the Amazon FreeRTOS Demo Project in TI Code Composer -**Import the Amazon FreeRTOS Sample Code into TI Code Composer** +**To import the Amazon FreeRTOS demo into TI Code Composer** 1. Open TI Code Composer, and choose **OK** to accept the default workspace name\. @@ -160,11 +160,11 @@ The certificate and private key are hard\-coded for demonstration purposes only\ 1. From **Project**, choose **Build Project** to make sure the project compiles without errors or warnings\. -**Subscribe to MQTT topic** +**To subscribe to MQTT topic** **Note** Before you run the Amazon FreeRTOS samples, do the following: -1. Make sure the Sense On Power \(SOP\) jumper on your Texas Instruments CC3220SF\-LAUNCHXL is in position 0\. For more information, see [CC3200 SimpleLink User's Guide](http://www.ti.com/lit/ug/swru372b/swru372b.pdf)\. +1. Make sure the Sense On Power \(SOP\) jumper on your Texas Instruments CC3220SF\-LAUNCHXL is in position 0\. For more information, see [CC3220 SimpleLink User's Guide](http://www.ti.com/lit/ug/swru463b/swru463b.pdf)\. 1. Use a USB cable to connect your Texas Instruments CC3220SF\-LAUNCHXL to your computer\. @@ -174,7 +174,7 @@ Before you run the Amazon FreeRTOS samples, do the following: 1. In **Subscription topic**, enter **freertos/demos/echo**, and then choose **Subscribe to topic**\. -**Run the Amazon FreeRTOS samples in TI Code Composer** +**To run the Amazon FreeRTOS demo in TI Code Composer** 1. Rebuild your project\. @@ -184,9 +184,9 @@ Before you run the Amazon FreeRTOS samples, do the following: In the MQTT client in the AWS IoT console, you should see the MQTT messages sent by your device\. -### Build and Run Amazon FreeRTOS Samples in IAR Embedded Workbench +### Build and Run Amazon FreeRTOS Demo Project in IAR Embedded Workbench -**Import the Amazon FreeRTOS Sample Code into IAR Embedded Workbench** +**To import the Amazon FreeRTOS demo into IAR Embedded Workbench** 1. Open IAR Embedded Workbench, choose **File**, and then choose **Open Workspace**\. @@ -194,9 +194,9 @@ In the MQTT client in the AWS IoT console, you should see the MQTT messages sent 1. Right\-click the project name \(`aws_demos`\), and then choose **Make**\. -**Subscribe to MQTT topic** +**To subscribe to MQTT topic** -1. Make sure the Sense On Power \(SOP\) jumper on your Texas Instruments CC3220SF\-LAUNCHXL is in position 0\. For more information, see [CC3200 SimpleLink User's Guide](http://www.ti.com/lit/ug/swru372b/swru372b.pdf)\. +1. Make sure the Sense On Power \(SOP\) jumper on your Texas Instruments CC3220SF\-LAUNCHXL is in position 0\. For more information, see [CC3220 SimpleLink User's Guide](http://www.ti.com/lit/ug/swru463b/swru463b.pdf)\. 1. Use a USB cable to connect your Texas Instruments CC3220SF\-LAUNCHXL to your computer\. @@ -206,7 +206,7 @@ In the MQTT client in the AWS IoT console, you should see the MQTT messages sent 1. In **Subscription topic**, enter **freertos/demos/echo**, and then choose **Subscribe to topic**\. -**Run the Amazon FreeRTOS samples in IAR Embedded Workbench** +**To run the Amazon FreeRTOS demo in IAR Embedded Workbench** 1. Rebuild your project\. diff --git a/doc_source/getting_started_windows.md b/doc_source/getting_started_windows.md index f2f1b68..dd1c26b 100755 --- a/doc_source/getting_started_windows.md +++ b/doc_source/getting_started_windows.md @@ -90,15 +90,15 @@ Amazon FreeRTOS is a C language project, and the certificate and private key mus **Note** The certificate and private key should be hard\-coded for demonstration purposes only\. Production\-level applications should store these files in a secure location\. -## Build and Run Amazon FreeRTOS Samples +## Build and Run Amazon FreeRTOS Demo Project -### Load the Amazon FreeRTOS Sample Code into Visual Studio +### Load the Amazon FreeRTOS Demo into Visual Studio 1. In Visual Studio, from the **File** menu, choose **Open**\. Choose **File/Solution**, navigate to `\demos\pc\windows\visual_studio\aws_demos.sln`, and then choose **Open**\. 1. From the **Build** menu, choose **Build Solution**, and make sure the solution builds without errors or warnings\. -### Run the Amazon FreeRTOS Samples +### Run the Amazon FreeRTOS Demo 1. Rebuild your Visual Studio project to pick up changes made in the header files\. diff --git a/doc_source/getting_started_xilinx.md b/doc_source/getting_started_xilinx.md index 09364f9..f348825 100755 --- a/doc_source/getting_started_xilinx.md +++ b/doc_source/getting_started_xilinx.md @@ -2,7 +2,7 @@ Before you begin, see [Prerequisites](freertos-prereqs.md)\. -If you do not have the Xilinx Avnet MicroZed Industrial IoT Kit, you can purchase one from [Avnet](http://www.zedboard.org/product/microzed-iiot-bundle-afreertos)\. +If you do not have the Xilinx Avnet MicroZed Industrial IoT Kit, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANtqUAH/MicroZed-IIoT-Bundle-with-Amazon-FreeRTOS)\. ## Setting Up the MicroZed Hardware @@ -110,7 +110,7 @@ Amazon FreeRTOS is a C language project, and the certificate and private key mus **Note** The certificate and private key should be hard\-coded for demonstration purposes only\. Production\-level applications should store these files in a secure location\. -## Build and Run Amazon FreeRTOS Samples +## Build and Run Amazon FreeRTOS Demo Project Now that you have configured your project, you are ready to build and run the demo project on your board\. @@ -124,7 +124,7 @@ Before you run the demo project, use the MQTT client in the AWS IoT console to s 1. In **Subscription topic**, enter **freertos/demos/echo**, and then choose **Subscribe to topic**\. -### Open the Amazon FreeRTOS Sample Code in the XSDK IDE +### Open the Amazon FreeRTOS Demo in the XSDK IDE 1. Launch the XSDK IDE with the workspace directory set to `\demos\xilinx\microzed\xsdk`\. @@ -151,7 +151,7 @@ If you see a warning at the top of the **Import Projects** page \("Some projects 1. In **New String Substitution Variable**, for **Name**, enter **AFR\_ROOT**\. For **Value**, enter the root path of the `aws_demos`\. Choose **OK**, and then choose **OK** to save the variable and close **Preferences**\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/xsdk-string-sub.png) -### Build the Amazon FreeRTOS Project +### Build the Amazon FreeRTOS Demo Project 1. In the XSDK IDE, from the menu, choose **Project**, and then choose **Clean**\. @@ -179,9 +179,9 @@ Before you debug, be sure to back up any content that you have on the MicroSD ca **Note** The first time you run the application, a new certificate\-key pair is generated\. For subsequent runs, you can comment out `vDevModeKeyProvisioning()` in the `main.c` file before you rebuild the images and the `BOOT.bin` file\. This prevents the copying of the certificates and key to storage on every run\. -You can opt to boot your MicroZed board from a MicroSD card or from QSPI flash to run the Amazon FreeRTOS demo project\. For instructions, see [Generate the Boot Image for the Amazon FreeRTOS Project](#xilinx-build-boot-image) and [Run the Amazon FreeRTOS Project](#xilinx-run)\. +You can opt to boot your MicroZed board from a MicroSD card or from QSPI flash to run the Amazon FreeRTOS demo project\. For instructions, see [Generate the Boot Image for the Amazon FreeRTOS Demo Project](#xilinx-build-boot-image) and [Run the Amazon FreeRTOS Demo Project](#xilinx-run)\. -### Generate the Boot Image for the Amazon FreeRTOS Project +### Generate the Boot Image for the Amazon FreeRTOS Demo Project 1. In the XSDK IDE, right\-click **aws\_demos**, and then choose **Create Boot Image**\. @@ -198,7 +198,7 @@ You can opt to boot your MicroZed board from a MicroSD card or from QSPI flash 1. On **Create Boot Image**, choose **Create Image**\. On **Override Files**, choose **OK** to overwrite the existing `aws_demos.bif` and generate the `BOOT.bin` file at `demos\xilinx\microzed\xsdk\aws_demos\bootimage\BOOT.bin`\. -### Run the Amazon FreeRTOS Project +### Run the Amazon FreeRTOS Demo Project To run the Amazon FreeRTOS demo project, you can boot your MicroZed board from a MicroSD card or from QSPI flash\. @@ -217,7 +217,7 @@ Format the MicroSD card that is provided with the Xilinx MicroZed Industrial IoT 1. Press the RST button to reset the device and start booting the application\. You can also unplug the USB\-UART cable from the USB\-UART port, and then reinsert the cable\. -#### Boot the Amazon FreeRTOS Project from QSPI flash +#### Boot the Amazon FreeRTOS Demo Project from QSPI flash 1. Set your MicroZed board's boot mode jumpers to the JTAG boot mode: ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/xilinx-jtag.png) @@ -255,6 +255,6 @@ Be sure to back up any content that you have on the MicroSD card\. ## Troubleshooting ### General Troubleshooting Tips -+ If you encounter build errors that are related to incorrect paths, try to clean and rebuild the project, as described in [Build the Amazon FreeRTOS Project](#xilinx-freertos-build-project)\. ++ If you encounter build errors that are related to incorrect paths, try to clean and rebuild the project, as described in [Build the Amazon FreeRTOS Demo Project](#xilinx-freertos-build-project)\. **Note** If you are using Windows, make sure that you use forward slashes when you set the string substitution variables in the Windows XSDK IDE\. \ No newline at end of file diff --git a/doc_source/gg-demo.md b/doc_source/gg-demo.md index 72f41ef..c3b587a 100755 --- a/doc_source/gg-demo.md +++ b/doc_source/gg-demo.md @@ -7,13 +7,7 @@ After you have a core running the Greengrass software, create an AWS IoT thing, After you have created an IoT thing for your Amazon FreeRTOS device, follow the instructions to set up your environment and build Amazon FreeRTOS on one of the supported devices: **Note** -Use the [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) instructions, but instead of downloading one of the predefined Connect to AWS IoT\- XX configurations \(where XX is TI, ST, NXP, Microchip, or Windows\), download one of the Connect to AWS IoT Greengrass \- XX configurations \(where XX is TI, ST, NXP, Microchip, or Windows\)\. Follow the steps in "Configure Your Project\." Return to this topic after you have built Amazon FreeRTOS for your device\. -+ [Getting Started with the Texas Instruments CC3220SF\-LAUNCHXL](getting_started_ti.md) -+ [Getting Started with the STMicroelectronics STM32L4 Discovery Kit IoT Node](getting_started_st.md) -+ [Getting Started with the NXP LPC54018 IoT Module](getting_started_nxp.md) -+ [ Getting Started with the Microchip Curiosity PIC32MZEF](getting_started_mch.md) -+ [Getting Started with the Infineon XMC4800 IoT Connectivity Kit](getting_started_infineon.md) -+ [Getting Started with the FreeRTOS Windows Simulator](getting_started_windows.md) +Use the [Registering Your MCU Board with AWS IoT](freertos-prereqs.md#get-started-freertos-thing) instructions, but instead of downloading one of the predefined Connect to AWS IoT\- XX configurations, download one of the Connect to AWS IoT Greengrass \- XX configurations\. Follow the steps in "Configure Your Project\." Return to this topic after you have built Amazon FreeRTOS for your device\. At this point, you have downloaded the Amazon FreeRTOS software, imported it into your IDE, and built the project without errors\. The project is already configured to run the Greengrass Connectivity demo\. In the AWS IoT console, choose **Test**, and then add a subscription to `freertos/demos/ggd`\. The demo publishes a series of messages to the Greengrass core\. The messages are also published to AWS IoT, where they are received by the AWS IoT MQTT client\. diff --git a/doc_source/index.md b/doc_source/index.md index 7c8609a..7736db9 100755 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -1,7 +1,7 @@ # Amazon FreeRTOS User Guide ----- -*****Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** +*****Copyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** ----- Amazon's trademarks and trade dress may not be used in @@ -15,7 +15,6 @@ Amazon's trademarks and trade dress may not be used in ----- ## Contents + [What Is Amazon FreeRTOS?](what-is-amazon-freertos.md) - + [Development Workflow](development-workflow.md) + [Getting Started with Amazon FreeRTOS](freertos-getting-started.md) + [Prerequisites](freertos-prereqs.md) + [Getting Started with the Texas Instruments CC3220SF-LAUNCHXL](getting_started_ti.md) @@ -25,6 +24,8 @@ Amazon's trademarks and trade dress may not be used in + [Getting Started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT](getting_started_espressif.md) + [Getting Started with the Infineon XMC4800 IoT Connectivity Kit](getting_started_infineon.md) + [Getting Started with the Xilinx Avnet MicroZed Industrial IoT Kit](getting_started_xilinx.md) + + [Getting Started with the Renesas Starter Kit+ for RX65N-2MB](getting_started_renesas.md) + + [Getting Started with the MediaTek MT7697Hx Development Kit](getting_started_mediatek.md) + [Getting Started with the FreeRTOS Windows Simulator](getting_started_windows.md) + [Getting Started with the Nordic nRF52840-DK](getting_started_nordic.md) + [Amazon FreeRTOS Developer Guide](freertos-dev-guide.md) @@ -46,15 +47,15 @@ Amazon's trademarks and trade dress may not be used in + [Amazon FreeRTOS Over-the-Air Updates](freertos-ota-dev.md) + [Over-the-Air Update Prerequisites](ota-prereqs.md) + [Create an Amazon S3 Bucket to Store Your Update](dg-ota-bucket.md) - + [Creating an OTA Update Service Role](create-service-role.md) - + [Creating an OTA User Policy](create-ota-user-policy.md) - + [Creating a Code-Signing Certificate](ota-code-sign-cert.md) + + [Create an OTA Update Service Role](create-service-role.md) + + [Create an OTA User Policy](create-ota-user-policy.md) + + [Create a Code-Signing Certificate](ota-code-sign-cert.md) + [Creating a Code-Signing Certificate for the Texas Instruments CC3200SF-LAUNCHXL](ota-code-sign-cert-ti.md) + [Creating a Code-Signing Certificate for the Microchip Curiosity PIC32MZEF](ota-code-sign-cert-mchip.md) + [Creating a Code-Signing Certificate for the Espressif ESP32](ota-code-sign-cert-esp.md) + [Creating a Code-Signing Certificate for the Amazon FreeRTOS Windows Simulator](ota-code-sign-cert-win.md) + [Creating a Code-Signing Certificate for Custom Hardware](ota-code-sign-cert-other.md) - + [Granting Access to Code Signing for Amazon FreeRTOS](code-sign-policy.md) + + [Grant Access to Code Signing for AWS IoT](code-sign-policy.md) + [Download Amazon FreeRTOS with the OTA Library](ota-download-freertos.md) + [OTA Tutorial](dev-guide-ota-workflow.md) + [Installing the Initial Firmware](dg-ota-initial-firmware.md) @@ -73,7 +74,8 @@ Amazon's trademarks and trade dress may not be used in + [Setting Up Cloudwatch Logs for OTA Updates](ota-logging.md) + [Logging AWS IoT OTA API Calls with AWS CloudTrail](iot-using-cloudtrail-afr.md) + [Troubleshooting OTA Updates with the Texas Instruments CC3220SF Launchpad](ota-troubleshooting-ti.md) - + [Amazon FreeRTOS Console User Guide](freertos-ocw-ug.md) + + [Amazon FreeRTOS Console](freertos-ocw-ug.md) + + [Troubleshooting Amazon FreeRTOS](troubleshooting_overview-afr.md) + [Amazon FreeRTOS Demo Projects](freertos-next-steps.md) + [Navigating the Demo Applications](freertos-mds-projects-struct.md) + [Bluetooth Low Energy Demo Applications (Beta)](ble-demo.md) @@ -82,7 +84,6 @@ Amazon's trademarks and trade dress may not be used in + [Greengrass Discovery Demo Application](gg-demo.md) + [OTA Demo Application](ota-demo.md) + [Demo Bootloader for the Microchip Curiosity PIC32MZEF](microchip-bootloader.md) -+ [Troubleshooting Amazon FreeRTOS](troubleshooting_overview-afr.md) + [Amazon FreeRTOS Porting Guide](porting-guide.md) + [Bootloader](porting-bootloader.md) + [Logging](porting-logging.md) @@ -90,6 +91,6 @@ Amazon's trademarks and trade dress may not be used in + [Security](porting-security.md) + [Using Custom Libraries with Amazon FreeRTOS](freertos-custom-libs.md) + [OTA Portable Abstraction Layer](porting-ota-pal.md) -+ [Amazon FreeRTOS Qualification Program](freertos-dqp.md) ++ [Amazon FreeRTOS Qualification Program](freertos-qualification-program.md) + [AWS IoT Device Tester for Amazon FreeRTOS User Guide](device-tester-for-freertos-ug.md) + [Permissions Policy Template](policy-template.md) \ No newline at end of file diff --git a/doc_source/ota-agent-library.md b/doc_source/ota-agent-library.md index 2b1b958..79a3db8 100755 --- a/doc_source/ota-agent-library.md +++ b/doc_source/ota-agent-library.md @@ -40,13 +40,13 @@ Amazon FreeRTOS | + - lib + - ota - | + ─ aws_ota_agent.c - | + ─ aws_ota_cbor.c - | + ─ portable - | + ─ README.md - | + ─ vendor - | + ─ board - | + ─ aws_ota_pal.c + | + - aws_ota_agent.c + | + - aws_ota_cbor.c + | + - portable + | + - README.md + | + - vendor + | + - board + | + - aws_ota_pal.c + - include + - aws_ota_agent.h + - private diff --git a/doc_source/ota-cli-workflow.md b/doc_source/ota-cli-workflow.md index a115e7f..92fd96d 100755 --- a/doc_source/ota-cli-workflow.md +++ b/doc_source/ota-cli-workflow.md @@ -10,11 +10,11 @@ To create an OTA update with the AWS CLI you: ## Digitally Signing Your Firmware Update -When you use the CLI to perform OTA updates, you can use Code Signing for Amazon FreeRTOS or sign your firmware update yourself\. +When you use the CLI to perform OTA updates, you can use Code Signing for AWS IoT or sign your firmware update yourself\. ### Signing Your Firmware Image with Code Signing for Amazon FreeRTOS -To sign your firmware image using Code Signing for Amazon FreeRTOS, you must install the [Code Signing Tools](https://tools.signer.aws.a2z.com/awssigner-tools.zip)\. Download the tools and read the README file for installation instructions\. For more information about Code Signing for Amazon FreeRTOS, see [Code Signing for Amazon FreeRTOS](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html)\. +To sign your firmware image using Code Signing for AWS IoT, you must install the [Code Signing Tools](https://tools.signer.aws.a2z.com/awssigner-tools.zip)\. Download the tools and read the README file for installation instructions\. For more information about Code Signing for AWS IoT, see [Code Signing for AWS IoT](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html)\. After you install and configure the code signing tools, copy your unsigned firmware image to your Amazon S3 bucket and start a code signing job with the following CLI commands\. The `put-signing-profile` command creates a reusable code\-signing profile\. The `start-signing-job` command starts the signing job\. @@ -59,7 +59,7 @@ To return a list of the available platforms and their `platformId` values, use t The signing job starts and writes the signed firmware image into the destination Amazon S3 bucket\. The file name for the signed firmware image is a GUID\. You need this file name when you create a stream\. You can find the generated file name by browsing to the Amazon S3 console and choosing your bucket\. If you don't see a file with a GUID file name, refresh your browser\. -The command displays a job ARN and a job ID\. You need these values later on\. For more information about Code Signing for Amazon FreeRTOS, see [Code Signing for Amazon FreeRTOS](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html)\. +The command displays a job ARN and a job ID\. You need these values later on\. For more information about Code Signing for AWS IoT, see [Code Signing for AWS IoT](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html)\. ### Signing Your Firmware Image Manually @@ -91,7 +91,7 @@ The bucket and key for the firmware to stream\. `bucket` The Amazon S3 bucket where your unsigned firmware image is stored\. `key` -The file name of your signed firmware image in the Amazon S3 bucket\. You can find this value in the Amazon S3 console by looking at the contents of your bucket\. If you are using Code Signing for Amazon FreeRTOS, the file name is a GUID generated by Code Signing for Amazon FreeRTOS\. +The file name of your signed firmware image in the Amazon S3 bucket\. You can find this value in the Amazon S3 console by looking at the contents of your bucket\. If you are using Code Signing for AWS IoT, the file name is a GUID generated by Code Signing for AWS IoT\. Use the `create-stream` CLI command to create a stream: @@ -116,7 +116,7 @@ The bucket name where the signed firmware image is stored and the key \(file nam `bucket` The Amazon S3 bucket where the signed firmware image is stored\. `key` -The key \(file name\) of the signed firmware image\. When you use Code Signing for Amazon FreeRTOS, this key is a GUID\. +The key \(file name\) of the signed firmware image\. When you use Code Signing for AWS IoT, this key is a GUID\. The following is an example stream\.json file: ``` @@ -215,7 +215,7 @@ One or more IoT thing ARNs that specify the devices to be updated by the OTA upd `role-arn` The ARN of your service role\. -The following is an example of a JSON file passed into the create\-ota\-update command that uses Code Signing for Amazon FreeRTOS : +The following is an example of a JSON file passed into the create\-ota\-update command that uses Code Signing for AWS IoT: ``` [ diff --git a/doc_source/ota-code-sign-cert-esp.md b/doc_source/ota-code-sign-cert-esp.md index b1ab52b..92fdfc7 100755 --- a/doc_source/ota-code-sign-cert-esp.md +++ b/doc_source/ota-code-sign-cert-esp.md @@ -38,4 +38,4 @@ The Espressif ESP32 boards support a self\-signed SHA256 with ECDSA code\-signin This command displays an ARN for your certificate\. You need this ARN when you create an OTA update job\. **Note** -This step is written with the assumption that you are going to use Code Signing for Amazon FreeRTOS to sign your firmware images\. Although the use of Code Signing for Amazon FreeRTOS is recommended, you can sign your firmware images manually\. \ No newline at end of file +This step is written with the assumption that you are going to use Code Signing for AWS IoT to sign your firmware images\. Although the use of Code Signing for AWS IoT is recommended, you can sign your firmware images manually\. \ No newline at end of file diff --git a/doc_source/ota-code-sign-cert-mchip.md b/doc_source/ota-code-sign-cert-mchip.md index b97840a..e09fe6f 100755 --- a/doc_source/ota-code-sign-cert-mchip.md +++ b/doc_source/ota-code-sign-cert-mchip.md @@ -38,4 +38,4 @@ The Microchip Curiosity PIC32MZEF supports a self\-signed SHA256 with ECDSA code This command displays an ARN for your certificate\. You need this ARN when you create an OTA update job\. **Note** -This step is written with the assumption that you are going to use Code Signing for Amazon FreeRTOS to sign your firmware images\. Although the use of Code Signing for Amazon FreeRTOS is recommended, you can sign your firmware images manually\. \ No newline at end of file +This step is written with the assumption that you are going to use Code Signing for AWS IoT to sign your firmware images\. Although the use of Code Signing for AWS IoT is recommended, you can sign your firmware images manually\. \ No newline at end of file diff --git a/doc_source/ota-code-sign-cert-ti.md b/doc_source/ota-code-sign-cert-ti.md index e205bf5..0ee6f78 100755 --- a/doc_source/ota-code-sign-cert-ti.md +++ b/doc_source/ota-code-sign-cert-ti.md @@ -16,7 +16,7 @@ Install the [SimpleLink CC3220 SDK version 2\.10\.00\.04](http://www.ti.com/tool The certificates in the SimpleLink CC3220 SDK are in DER format\. To create a self‐signed code\-signing certificate, you must convert them to PEM format\. -Follow these steps to create a code\-signing certificate that is linked to the Texas Instruments playground certificate hierarchy and meets AWS Certificate Manager and Code Signing for Amazon FreeRTOS criteria\. +Follow these steps to create a code\-signing certificate that is linked to the Texas Instruments playground certificate hierarchy and meets AWS Certificate Manager and Code Signing for AWS IoT criteria\. **To create a self‐signed code signing certificate** @@ -87,4 +87,4 @@ You write the `tisigner.crt.der` certificate onto the TI development board later This command displays an ARN for your certificate\. You need this ARN when you create an OTA update job\. **Note** -This step is written with the assumption that you are going to use Code Signing for Amazon FreeRTOS to sign your firmware images\. Although the use of Code Signing for Amazon FreeRTOS is recommended, you can sign your firmware images manually\. \ No newline at end of file +This step is written with the assumption that you are going to use Code Signing for AWS IoT to sign your firmware images\. Although the use of Code Signing for AWS IoT is recommended, you can sign your firmware images manually\. \ No newline at end of file diff --git a/doc_source/ota-code-sign-cert-win.md b/doc_source/ota-code-sign-cert-win.md index 149624b..39195b6 100755 --- a/doc_source/ota-code-sign-cert-win.md +++ b/doc_source/ota-code-sign-cert-win.md @@ -38,4 +38,4 @@ The Amazon FreeRTOS Windows simulator requires a code\-signing certificate with This command displays an ARN for your certificate\. You need this ARN when you create an OTA update job\. **Note** -This step is written with the assumption that you are going to use Code Signing for Amazon FreeRTOS to sign your firmware images\. Although the use of Code Signing for Amazon FreeRTOS is recommended, you can sign your firmware images manually\. \ No newline at end of file +This step is written with the assumption that you are going to use Code Signing for AWS IoT to sign your firmware images\. Although the use of Code Signing for AWS IoT is recommended, you can sign your firmware images manually\. \ No newline at end of file diff --git a/doc_source/ota-code-sign-cert.md b/doc_source/ota-code-sign-cert.md index e5919a2..b1eb3ef 100755 --- a/doc_source/ota-code-sign-cert.md +++ b/doc_source/ota-code-sign-cert.md @@ -1,5 +1,12 @@ -# Creating a Code\-Signing Certificate +# Create a Code\-Signing Certificate To digitally sign firmware images, you need a code\-signing certificate and private key\. For testing purposes, you can create a self‐signed certificate and private key\. For production environments, purchase a certificate through a well‐known certificate authority \(CA\)\. -Different platforms require different types of code\-signing certificates\. The following section describes how to create code\-signing certificates for each of the Amazon FreeRTOS\-qualified platforms\. \ No newline at end of file +Different platforms require different types of code\-signing certificates\. The following sections describe how to create code\-signing certificates for different Amazon FreeRTOS\-qualified platforms\. + +**Topics** ++ [Creating a Code\-Signing Certificate for the Texas Instruments CC3200SF\-LAUNCHXL](ota-code-sign-cert-ti.md) ++ [Creating a Code\-Signing Certificate for the Microchip Curiosity PIC32MZEF](ota-code-sign-cert-mchip.md) ++ [Creating a Code\-Signing Certificate for the Espressif ESP32](ota-code-sign-cert-esp.md) ++ [Creating a Code\-Signing Certificate for the Amazon FreeRTOS Windows Simulator](ota-code-sign-cert-win.md) ++ [Creating a Code\-Signing Certificate for Custom Hardware](ota-code-sign-cert-other.md) \ No newline at end of file diff --git a/doc_source/ota-prereqs.md b/doc_source/ota-prereqs.md index b187a7c..e5ec93b 100755 --- a/doc_source/ota-prereqs.md +++ b/doc_source/ota-prereqs.md @@ -1,10 +1,9 @@ # Over\-the\-Air Update Prerequisites -To use over\-the\-air updates, you need to: -+ Create an S3 bucket to store your firmware update\. -+ Create an OTA service role\. -+ Create an OTA user policy\. -+ Create or purchase a code\-signing certificate\. -+ If you are using Code Signing for Amazon FreeRTOS, import your code\-signing key into ACM\. -+ If you are using Code Signing for Amazon FreeRTOS, create a code\-signing policy\. -+ Download Amazon FreeRTOS with the OTA library for your platform or, if you are not using Amazon FreeRTOS, provide your own OTA agent implementation\. \ No newline at end of file +To use over\-the\-air updates, you need to do the following: ++ [Create an Amazon S3 Bucket to Store Your Update](dg-ota-bucket.md)\. ++ [Create an OTA Update Service Role](create-service-role.md)\. ++ [Create an OTA User Policy](create-ota-user-policy.md)\. ++ [Create a Code\-Signing Certificate](ota-code-sign-cert.md)\. ++ If you are using Code Signing for AWS IoT, [Grant Access to Code Signing for AWS IoT](code-sign-policy.md)\. ++ [Download Amazon FreeRTOS with the OTA Library](ota-download-freertos.md)\. If you are not using Amazon FreeRTOS, you can provide your own OTA agent implementation\. \ No newline at end of file diff --git a/doc_source/secure-sockets.md b/doc_source/secure-sockets.md index 2cdd679..6583c3c 100755 --- a/doc_source/secure-sockets.md +++ b/doc_source/secure-sockets.md @@ -44,20 +44,20 @@ Amazon FreeRTOS Secure Sockets library features include: ``` Amazon FreeRTOS | -+ ─ lib - + ─ include - | + ─ aws_secure_sockets.h - | + ─ private - | + ─ aws_secure_sockets_config_defaults.h - + ─ secure_sockets ++ - lib + + - include + | + - aws_secure_sockets.h + | + - private + | + - aws_secure_sockets_config_defaults.h + + - secure_sockets + - portable + - ... - + ─ aws_secure_sockets.c + + - aws_secure_sockets.c ``` ## Troubleshooting -### Error codes +### Error codes The error codes that the Amazon FreeRTOS Secure Sockets library returns are negative values\. For more information about each error code, see Secure Sockets Error Codes in the [Secure Sockets API Reference](https://docs.aws.amazon.com/freertos/latest/lib-ref/html2/secure_sockets/index.html)\. diff --git a/doc_source/what-is-amazon-freertos.md b/doc_source/what-is-amazon-freertos.md index d14c4c7..e17affe 100755 --- a/doc_source/what-is-amazon-freertos.md +++ b/doc_source/what-is-amazon-freertos.md @@ -5,7 +5,6 @@ Amazon FreeRTOS consists of the following components: + Amazon FreeRTOS libraries for connectivity, security, and over\-the\-air \(OTA\) updates\. + A console that allows you to download a zip file that contains everything you need to get started with Amazon FreeRTOS\. + Over\-the\-air \(OTA\) Updates\. -+ The Amazon FreeRTOS Qualification Program\. ## The FreeRTOS Kernel @@ -20,11 +19,10 @@ Amazon FreeRTOS includes libraries that enable you to: + Securely connect devices to the AWS IoT cloud using MQTT and device shadows\. + Discover and connect to AWS IoT Greengrass cores\. + Manage Wi\-Fi connections\. -+ Audit the configuration of your devices, monitor connected devices to detect abnormal behavior, and to mitigate security risks\. For more information, see [AWS IoT Device Defender](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender.html)\. Amazon FreeRTOS provides a library that enables your Amazon FreeRTOS\-based devices to write metrics to AWS IoT Device Defender\. For more information, see [Amazon FreeRTOS Device Defender Library](https://docs.aws.amazon.com/freertos/latest/userguide/afr-device-defender-library.html)\. -**Note** -The Device Defender library currently works on the Microchip Curiosity PIC32MZEF development board and the Windows simulator\. + Listen for and process over\-the\-air \(OTA\) updates\. +For more information, see [Amazon FreeRTOS Libraries](https://docs.aws.amazon.com/freertos/latest/userguide/dev-guide-freertos-libraries.html)\. + ## Amazon FreeRTOS Console The [Amazon FreeRTOS console](https://console.aws.amazon.com/freertos) enables you to configure and download a package that contains everything you need to write an application for your microcontroller\-based devices: @@ -45,6 +43,8 @@ The Amazon FreeRTOS console is part of the AWS IoT console\. You can find it by 1. Under **Amazon FreeRTOS Device Software** choose **Configure Download**\. +For more information, see [Amazon FreeRTOS Console](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-ocw-ug.html)\. + ## Downloading Amazon FreeRTOS Source Code You can download the RTOS kernel and software libraries from the [Amazon FreeRTOS console](https://console.aws.amazon.com/freertos) or from [GitHub](https://github.com/aws/amazon-freertos)\. @@ -59,8 +59,16 @@ Internet\-connected devices can be in use for a long time, and must be updated p + Monitor the progress of a deployment\. + Debug a failed deployment\. -When you send files over the air, it is a best practice to digitally sign them so that the devices that receive the files can verify they have not been tampered with en route\. You can use Code Signing for Amazon FreeRTOS to sign and encrypt your files or you can sign your files with your own code\-signing tools\. For more information about Code Signing for Amazon FreeRTOS, see the [Code Signing for Amazon FreeRTOS Developer Guide](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html)\. +When you send files over the air, it is a best practice to digitally sign them so that the devices that receive the files can verify they have not been tampered with en route\. You can use Code Signing for AWS IoT to sign and encrypt your files or you can sign your files with your own code\-signing tools\. For more information about Code Signing for AWS IoT, see the [Code Signing for AWS IoT Developer Guide](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html)\. For more information about OTA updates, see: + [Amazon FreeRTOS Over\-the\-Air Updates](freertos-ota-dev.md) -+ [OTA Demo Application](ota-demo.md) \ No newline at end of file ++ [OTA Demo Application](ota-demo.md) + +## Development Workflow + +You start development by downloading Amazon FreeRTOS\. You unzip the package and import it into your IDE\. You can then develop an application on your selected hardware platform and manufacture and deploy these devices using the development process appropriate for your device\. Deployed devices can connect to the AWS IoT service or AWS IoT Greengrass as part of a complete IoT solution\. The following diagram shows the development workflow and the subsequent connectivity from Amazon FreeRTOS\-based devices\. + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/workflow.png) + +For more information about developing applications with Amazon FreeRTOS, see the [Amazon FreeRTOS Developer Guide](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-dev-guide.html)\. \ No newline at end of file