From 913b4df9e30930437f375ef7de54688c45e7061c Mon Sep 17 00:00:00 2001 From: Simone Orru Date: Thu, 12 Dec 2024 09:36:50 +0100 Subject: [PATCH] Apply suggestions from code review Signed-off-by: Simone Orru --- samples/astarte_app/README.md | 23 ++++++++++++----------- samples/astarte_app/README_NXP.md | 27 ++++++++++++++------------- 2 files changed, 26 insertions(+), 24 deletions(-) diff --git a/samples/astarte_app/README.md b/samples/astarte_app/README.md index 2df478fb..bb54c079 100644 --- a/samples/astarte_app/README.md +++ b/samples/astarte_app/README.md @@ -6,7 +6,7 @@ SPDX-License-Identifier: Apache-2.0 ## Samples organization -The sample app in this folder contains code to send all data types supported by astarte. +The sample app in this folder contains code to send all data types supported by Astarte. The sample folder also contains: - Board specific overlays and configurations. Contained in the `astarte_app/boards` folder. @@ -21,7 +21,7 @@ running the `west generate-interfaces` command and should not be modified manual The sample contains three threads: - A master application thread that will handle Ethernet/Wifi reconnection. - A secondary thread that will manage the Astarte device and handle reception of data from Astarte. -- The third thread that sends data to astarte of the configured types. +- The third thread that sends data to Astarte of the configured types. The sample will connect to Astarte and remain connected for the time it takes to send the data. Intervals between send of different types of data can be configured. @@ -30,7 +30,7 @@ timeout to allow reception of test messages. After the operational time of the device has concluded, the device will disconnect and the sample will terminate. -Take a look a the [Kconfig](astarte_app/Kconfig) file or use menuconfig to test out different +Take a look at the [Kconfig](astarte_app/Kconfig) file or use menuconfig to test out different transmission types and timeouts. ## Samples configuration @@ -38,7 +38,7 @@ transmission types and timeouts. ### Configuration for demonstration non-TLS capable Astarte This option assumes you are using this example with an Astarte instance similar to the -one explained in the +one deployed by following the [Astarte quick instance](https://docs.astarte-platform.org/device-sdks/common/astarte_quick_instance.html) tutorial. @@ -83,7 +83,7 @@ array a valid CA certificate in the PEM format. ### Configuration of secrets in ignored files Some of the data configured in the `prj.conf` files could be private. -Data like wifi passwords or even the astarte credential secret could be configured in a +Data like WiFi passwords or even the Astarte credential secret could be configured in a `private.conf` file. You can have a `private.conf` file in the [astarte_app](https://github.com/astarte-platform/astarte-device-sdk-zephyr/tree/master/samples/astarte_app) folder. This file is specified in the `.gitignore` and won't be committed. @@ -108,10 +108,11 @@ need to be run as a root user. ## Astarte app sample overview -This samle shows the basic operation an average user would perform using an astarte device: +This sample shows the basic operation an average user would perform using an Astarte device: - **How to opionally register the device** - **How connection is established and how callbacks can be used to receive data or assess -the connection status.** The samples configures callback for each type of data that can be received from astarte. +the connection status.** The samples configures callback for each type of data that can be received +from Astarte. Received values are logged using the logging module. - **How different types of data can be sent trough the device.** @@ -119,8 +120,8 @@ The trasmission is divided in four steps that can be enabled indipendently to te device and server behaviour. Kconfig values control the compilation of these steps, here are presented in the order in which they are executed: - [registration](#Registration): Calls the sdk api to register a device given a pairing jwt token. -- [datastream individual send](#Individuals_reception): Transmit individual data to astarte. -- [datastream object send](#Objects_reception): Transmit object data to astarte. +- [datastream individual send](#Individuals_reception): Transmit individual data to Astarte. +- [datastream object send](#Objects_reception): Transmit object data to Astarte. - [properties set/unset individual](#Properties_reception): set and unset individual properties. Each one of those steps has a corresponding configuration menu that lets you enable @@ -128,7 +129,7 @@ and disable it's compilation. It is also possible to configure a timeout in seco wait for before sending each type of data. If no transmission is enabled it is possible to configure a timeout to wait for before disconnecting the device and stopping the sample. This allows the device -to log messages received from astarte. +to log messages received from Astarte. Run menuconfig to try out different values. ## Sample configurable steps @@ -139,7 +140,7 @@ This step can be enabled through the `Registration` menu and shows how to regist a remote Astarte instance using the pairing APIs provided in this library. The credential secret created will be stored in the NVS. A pairing JWT is needed and the device must have no credential secret already associated. You can -wipe it from the web interface of astarte if needed. +wipe it from the web interface of Astarte if needed. ### Individuals transmission diff --git a/samples/astarte_app/README_NXP.md b/samples/astarte_app/README_NXP.md index de2e954a..3eca7c48 100644 --- a/samples/astarte_app/README_NXP.md +++ b/samples/astarte_app/README_NXP.md @@ -13,7 +13,7 @@ SPDX-License-Identifier: Apache-2.0 [![Category badge](https://img.shields.io/badge/Category-CLOUD%20CONNECTED%20DEVICES-yellowgreen)](https://mcuxpresso.nxp.com/appcodehub?search=cloud%20connected%20devices) [![Toolchain badge](https://img.shields.io/badge/Toolchain-VS%20CODE-orange)](https://github.com/nxp-mcuxpresso/vscode-for-mcux/wiki) -Astarte is an Open Source IoT platform focused on data management. It takes care of everything from +Astarte is an open source IoT platform focused on data management. It takes care of everything from collecting data from devices to delivering data to end-user applications. This demo application shows how to create an Astarte device using the Zephyr RTOS framework on the i.MX RT1064 evaluation kit. @@ -61,7 +61,7 @@ Additionally, each board should provide a dedicated flash partition for Astarte. ### 3.1 Step 1 You will need an Astarte instance to which the device will connect. -The easiest way to set up one is to follow the +The easiest way to set one up is to follow the [Astarte quick instance](https://docs.astarte-platform.org/device-sdks/common/astarte_quick_instance.html) tutorial. The tutorial guides you through setting up an Astarte instance on a local host machine. Make sure @@ -145,13 +145,12 @@ Configure the device to connect to our Astarte instance by changing the followin - `REALM_NAME` is the name of the Astarte realm - `DEVICE_ID` is the device identifier used to connect to Astarte - `CREDENTIAL_SECRET` is the credential secret for the device obtained during off-board - registration. This option should be set only when the registration of the device takes place - manually on Astarte. + registration. This option should be set only when the device is registered manually on Astarte. - `ACCESS_TOKEN` is the access token for the device to be used for on-board registration. This - option should be set only when the registration of the device takes place on-board. + option should be set only when the device is registered on-board. Additionally, the sample can be fine-tuned enabling or disabling some features. -- `CONFIG_DEVICE_REGISTRATION` when activated the device will perform on board registration using +- `CONFIG_DEVICE_REGISTRATION` when activated the device will perform onboard registration using the access token. - `CONFIG_DEVICE_INDIVIDUAL_TRANSMISSION`, `CONFIG_DEVICE_OBJECT_TRANSMISSION`, `CONFIG_DEVICE_PROPERTY_SET_TRANSMISSION` and `CONFIG_DEVICE_PROPERTY_UNSET_TRANSMISSION` enable @@ -159,19 +158,21 @@ Additionally, the sample can be fine-tuned enabling or disabling some features. ## 4. Results -Upon running the code the demo application will display on the serial monitor its progression. -The device will first connect to Astarte performing an on-board device registration if configured +Upon running the code the demo application will display its progress on the serial monitor. +The device will first connect to Astarte performing an onboard device registration if configured to do so or using the credential secret if the registration has been performed off-board. It will then transmit some data while listening for incoming messages from Astarte. -Once transmission has been accomplished the device will gracefully terminate the connection and -be destroyed. +Once the transmission is complete the device will gracefully terminate the connection and be +destroyed. ## 5. Support -For more information about Astarte check out the [Astarte documentation](https://docs.astarte-platform.org/). -Or check out our projects on [GitHub](https://github.com/astarte-platform). +For more information about Astarte, refer to the +[Astarte documentation](https://docs.astarte-platform.org/) or explore the related projects on +[GitHub](https://github.com/astarte-platform). -Questions regarding the content/correctness of this example can be entered as Issues within this GitHub repository. +Questions regarding the content/correctness of this example can be entered as Issues within this +GitHub repository. ## 6. Release Notes | Version | Description / Update | Date |