doc: Improve wording, styling, links

TheThingsIndustries · Oct 27, 2021 · d2b7418 · d2b7418
1 parent e84faa5
commit d2b7418
Show file tree

Hide file tree

Showing 47 changed files with 363 additions and 196 deletions.
diff --git a/doc/content/applications/se-app-template/_index.md b/doc/content/applications/se-app-template/_index.md
@@ -5,6 +5,6 @@ weight: -1
 distributions: null
 ---
 
-This [application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/app_template) provides a bloat-free template for starting with application development.
+The [app_template](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/app_template) provides a bloat-free template for starting with application development.
 
-Developers are expected to customize this application, add their source files and build configurations according to their needs.
+Developers can customize this application, add their source files and build configurations according to their needs.
diff --git a/doc/content/applications/se-app-template/configuration.md b/doc/content/applications/se-app-template/configuration.md
@@ -5,4 +5,5 @@ weight: -1
 ---
 
 This application does not require any additional configurations to function.
-Any application specific configurations should be added to `conf/app_conf.h`.
+
+Any application-specific configurations should be added to `conf/app_conf.h`.
diff --git a/doc/content/applications/se-app-template/setup.md b/doc/content/applications/se-app-template/setup.md
@@ -8,9 +8,9 @@ This application does not require any additional setup as it acts as a template.
 You can add more functionality to this application by following the steps below:
 
 1. Add your source files in `app_template`
-2. Add your library paths to `CMakeLists.txt` and STM32CubeIDE `.cproject`,`.project` similar to`GNSE_BSP`library
+2. Add your library paths to the `CMakeLists.txt` file and STM32CubeIDE `.cproject`, `.project` similar to`GNSE_BSP`library
 
-> **Note:** Keep in mind that you can also see how this is done in the other example applications located in `app` folder.
+{{< note >}} Keep in mind that you can also see how this is done in the other example applications located in `app` folder. {{</ note >}}
 
 If you are satisfied with the application behavior, you can rename it and add the new app name to `CMakeLists.txt` under `APP_LIST`.
 

diff --git a/doc/content/applications/se-basic-azurertos/_index.md b/doc/content/applications/se-basic-azurertos/_index.md
@@ -5,6 +5,8 @@ weight: 2
 distributions: null
 ---
 
-This [application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic_azurertos) provides a basic example of [Microsoft Azure RTOS](https://azure.microsoft.com/en-us/services/rtos/) functionality.
+The [basic_azurertos application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic_azurertos) provides a basic example of [Microsoft Azure RTOS](https://azure.microsoft.com/en-us/services/rtos/) functionality.
+
+<!--more-->
 
 The application creates two threads and a message queue. Thread 1 attempts to pass a message to thread 2 via the queue and then sleeps for `TX_DELAY`. Thread 2 blinks the LED when the sent message is successfully received.
diff --git a/doc/content/applications/se-basic-azurertos/configuration.md b/doc/content/applications/se-basic-azurertos/configuration.md
@@ -10,7 +10,7 @@ Key configurations are stated below:
 
 ### Azure RTOS
 
-- `MEM_BYTE_POOL_SIZE`,`THREAD_STACK_SIZE`,`QUEUE_SIZE` in bytes defines Azure RTOS memory pool, threads and queue sizes
+`MEM_BYTE_POOL_SIZE`,`THREAD_STACK_SIZE`,`QUEUE_SIZE` in bytes defines Azure RTOS memory pool, threads and queue sizes:
 
 ```c
 #define MEM_BYTE_POOL_SIZE 9120
@@ -22,13 +22,13 @@ Key configurations are stated below:
 
 ### App activity
 
-- `GNSE_TINY_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity
+`GNSE_TINY_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity:
 
 ```c
 #define GNSE_TINY_TRACER_ENABLE 1
 ```
 
-- `TX_DELAY` in milliseconds defines the message passing rate from thread 1 to thread 2.
+`TX_DELAY` in milliseconds defines the message passing rate from thread 1 to thread 2:
 
 ```c
 #define TX_DELAY                 (5000)
diff --git a/doc/content/applications/se-basic-bootloader/_index.md b/doc/content/applications/se-basic-bootloader/_index.md
@@ -5,13 +5,13 @@ weight: 3
 distributions: null
 ---
 
-The [application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic_bootloader) provides a basic bootloader that can be combined with other applications to perform a specific functionality at boot time.
+The [basic_bootloader application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic_bootloader) provides a basic bootloader that can be combined with other applications to perform a specific functionality at boot time.
 
 <!--more-->
 
 > If you want to learn more about the purpose of a bootloader, we recommend reading this great [blog post](https://interrupt.memfault.com/blog/how-to-write-a-bootloader-from-scratch).
 
 `basic_bootloader` performs one of two functionalities based on the GNSE button:
 
-1. If the button is not pressed -> boots the user flashed application
-2. If the button is pressed long enough -> boots the ST internal bootloader
+1. If the button is not pressed &#8594; boots the user flashed application
+2. If the button is pressed long enough &#8594; boots the ST internal bootloader
diff --git a/doc/content/applications/se-basic-bootloader/configuration.md b/doc/content/applications/se-basic-bootloader/configuration.md
@@ -6,7 +6,7 @@ weight: -1
 
 `basic_bootloader` key configurations:
 
-### Memory Map
+### Memory map
 
 The internal flash (ROM) memory map can be configured to accommodate a bootloader and an application by adjusting the parameters defined in `memory_map.ld`.
 
@@ -19,7 +19,7 @@ APPROM   (rx)  : ORIGIN = 0x0800B000, LENGTH = 0x000035000   /* Flash memory ded
 
 The application behavior can be adjusted by modifying `conf/app_conf.h`.
 
-- `GNSE_TINY_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity
+`GNSE_TINY_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity:
 
 ```c
 #define GNSE_TINY_TRACER_ENABLE 1

diff --git a/doc/content/applications/se-basic-bootloader/setup.md b/doc/content/applications/se-basic-bootloader/setup.md
@@ -24,11 +24,11 @@ set(LINKER_SCRIPT ${MCU_DIR}/app.ld)
 
 If you are building using STM32CubeIDE, then there is no need to change the linker script when building a `basic_bootloader` binary as can be seen below.
 
-{{< figure src="../stm32cubeide_linker_bootloader.png" alt="bootloader STM32CubeIDE linker config" >}}
+{{< figure src="../stm32cubeide_linker_bootloader.png" alt="bootloader STM32CubeIDE linker config" class="plain" >}}
 
 But, make sure to change the application linker script from `../../../target/stm32wl55xx_flash.ld` to `../../../target/app.ld`.
 
-{{< figure src="../stm32cubeide_linker_app.png" alt="basic_lorawan STM32CubeIDE linker config" >}}
+{{< figure src="../stm32cubeide_linker_app.png" alt="basic_lorawan STM32CubeIDE linker config" class="plain" >}}
 
 ### Combining applications
 

diff --git a/doc/content/applications/se-basic-freertos/_index.md b/doc/content/applications/se-basic-freertos/_index.md
@@ -5,6 +5,8 @@ weight: 4
 distributions: null
 ---
 
-This [application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic_freertos) provides a basic example of [Amazon FreeRTOS](https://docs.aws.amazon.com/freertos/index.html) functionality.
+The [basic_freertos application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic_freertos) provides a basic example of [Amazon FreeRTOS](https://docs.aws.amazon.com/freertos/index.html) functionality.
+
+<!--more-->
 
 The application creates two threads and a message queue. Thread 1 attempts to pass a message to thread 2 via the queue and then sleeps for `TX_DELAY`. Thread 2 blinks the LED when the sent message is successfully received.
diff --git a/doc/content/applications/se-basic-freertos/configuration.md b/doc/content/applications/se-basic-freertos/configuration.md
@@ -4,7 +4,7 @@ description: ""
 weight: -1
 ---
 
-Key configurations are stated below:
+Key configurations are stated below.
 
 ### FreeRTOS
 
@@ -20,13 +20,13 @@ FreeRTOS configurations can be adjusted by modifying `conf/FreeRTOSConfig.h`.
 
 The application behavior can be adjusted by modifying `conf/app_conf.h`.
 
-- `GNSE_TINY_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity
+`GNSE_TINY_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity:
 
 ```c
 #define GNSE_TINY_TRACER_ENABLE 1
 ```
 
-- `TX_DELAY` in milliseconds defines the message passing rate from thread 1 to thread 2.
+`TX_DELAY` in milliseconds defines the message passing rate from thread 1 to thread 2:
 
 ```c
 #define TX_DELAY                 (5000)

diff --git a/doc/content/applications/se-basic-fuota/_index.md b/doc/content/applications/se-basic-fuota/_index.md
@@ -5,7 +5,7 @@ weight: 5
 distributions: null
 ---
 
-This [application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic_fuota) provides a basic example of LoRaWAN FUOTA (Firmware Update Over The Air) functionality.
+The [basic_fuota application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic_fuota) provides a basic example of LoRaWAN FUOTA (Firmware Update Over The Air) functionality.
 
 <!--more-->
 

diff --git a/doc/content/applications/se-basic-fuota/configuration.md b/doc/content/applications/se-basic-fuota/configuration.md
@@ -20,21 +20,21 @@ This application performs the FUOTA interoperability test, and the number of fra
 
 The application behavior can be adjusted by modifying `conf/app_conf.h`.
 
-- `GNSE_ADVANCED_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity
+`GNSE_ADVANCED_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity:
 
 ```c
 #define GNSE_ADVANCED_TRACER_ENABLE 1
 ```
 
-- `DEBUGGER_ON` enables the use of a debugger in low power mode
+`DEBUGGER_ON` enables the use of a debugger in low power mode:
 
 ```c
 #define DEBUGGER_ON       1
 ```
 
-> **Note:** Please keep in mind that it is best to disable the tracer and debugger functionalities to reduce power consumption.
+{{< note >}} Please keep in mind that it is best to disable the tracer and debugger functionalities to reduce power consumption. {{</ note >}}
 
-- `APPEUI`, `DEVEUI` and `APPKEY` allow the device to join the LoRaWAN network via OTAA.
+`APPEUI`, `DEVEUI` and `APPKEY` allow the device to join the LoRaWAN network via OTAA:
 
 ```c
 #define APPEUI                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
@@ -44,4 +44,4 @@ The application behavior can be adjusted by modifying `conf/app_conf.h`.
 #define APPKEY                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
 ```
 
-> **Note:** The default `0x00` is a place holder and you are required to change these values in order to achieve a successful activation. For testing purposes, these values can be random.
+{{< note >}} The default `0x00` is a placeholder and you are required to change these values in order to achieve a successful activation. For testing purposes, these values can be random. {{</ note >}}
diff --git a/doc/content/applications/se-basic-fuota/setup.md b/doc/content/applications/se-basic-fuota/setup.md
@@ -4,10 +4,10 @@ description: ""
 weight: 1
 ---
 
-### Device setup
+## Device setup
 
-- Follow [this](https://www.thethingsindustries.com/docs/devices/adding-devices/) guide to add your device to The Things Stack.
+Follow the [Adding Devices](https://www.thethingsindustries.com/docs/devices/adding-devices/) guide to add your device to The Things Stack.
 
-### Server setup
+## Server setup
 
-- You can use this example to [test FUOTA server](https://github.com/elsalahy/test-fuota-server) as starting point and you can follow the [`README.md`](https://github.com/elsalahy/test-fuota-server/blob/master/README.md) in order to set it up with a minimal effort
+You can use this example to [test FUOTA server](https://github.com/elsalahy/test-fuota-server) as starting point and you can follow the [`README.md`](https://github.com/elsalahy/test-fuota-server/blob/master/README.md) in order to set it up with a minimal effort.
diff --git a/doc/content/applications/se-basic-lorawan/_index.md b/doc/content/applications/se-basic-lorawan/_index.md
@@ -5,4 +5,4 @@ weight: 6
 distributions: null
 ---
 
-This [application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic_lorawan) serves as a basic template for LoRaWAN applications.
+The [basic_lorawan application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic_lorawan) serves as a basic template for LoRaWAN applications.
diff --git a/doc/content/applications/se-basic-lorawan/setup.md b/doc/content/applications/se-basic-lorawan/setup.md
@@ -10,7 +10,7 @@ You can add more functionality to this application by following the steps below:
 1. Add your source files in `app_template`
 2. Add your library paths to `CMakeLists.txt` and STM32CubeIDE `.cproject`,`.project` similar to`GNSE_BSP`library
 
-> **Note:** Keep in mind that you can also see how this is done in the other example applications located in `app` folder.
+{{< note >}} Keep in mind that you can also see how this is done in the other example applications located in `app` folder. {{</ note >}}
 
 If you are satisfied with the application behavior, you can rename it and add the new app name to `CMakeLists.txt` under `APP_LIST`.
 

diff --git a/doc/content/applications/se-basic/_index.md b/doc/content/applications/se-basic/_index.md
@@ -5,4 +5,4 @@ weight: 1
 distributions: null
 ---
 
-This [application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic) is mainly used to test the hardware of the GNSE.
+The [basic application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/basic) is mainly used to test the hardware of the GNSE.
diff --git a/doc/content/applications/se-basic/configuration.md b/doc/content/applications/se-basic/configuration.md
@@ -3,7 +3,7 @@ title: "Configuration"
 description: ""
 ---
 
-Some settings are available in `conf/app_conf.h` to set the testing time and amount for some peripherals.  For example, if you want to play the buzzer 4 times, your code should look like this:
+Some settings are available in `conf/app_conf.h` to set testing time and amount for peripherals.  For example, if you want to play the buzzer 4 times, your code should contain:
 
 ```
 #define NUMBER_BUZZER_PLAY 4

diff --git a/doc/content/applications/se-freefall-lorawan/_index.md b/doc/content/applications/se-freefall-lorawan/_index.md
@@ -5,7 +5,7 @@ weight: 7
 distributions: null
 ---
 
-This [application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/freefall_lorawan) is used to detect free fall events and also serves as a template for acceleration detection handling.
+The [freefall_lorawan application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/freefall_lorawan) is used to detect free fall events and also serves as a template for acceleration detection handling.
 
 <!--more-->
 

diff --git a/doc/content/applications/se-freertos-lorawan/_index.md b/doc/content/applications/se-freertos-lorawan/_index.md
@@ -5,4 +5,4 @@ weight: 8
 distributions: null
 ---
 
-This [application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/freertos_lorawan) provides an example of LoRaWAN class A application using [FreeRTOS](https://docs.aws.amazon.com/freertos/index.html).
+The [freertos_lorawan application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/freertos_lorawan) provides an example of LoRaWAN class A application using [FreeRTOS](https://docs.aws.amazon.com/freertos/index.html).
diff --git a/doc/content/applications/se-freertos-lorawan/configuration.md b/doc/content/applications/se-freertos-lorawan/configuration.md
@@ -20,13 +20,13 @@ FreeRTOS configurations can be adjusted by modifying `conf/FreeRTOSConfig.h`.
 
 The application behavior can be adjusted by modifying `conf/app_conf.h`.
 
-- `GNSE_TINY_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity
+`GNSE_TINY_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity:
 
 ```c
 #define GNSE_TINY_TRACER_ENABLE 1
 ```
 
-- `APPEUI`, `DEVEUI` and `APPKEY` allow the device to join the LoRaWAN network via OTAA.
+`APPEUI`, `DEVEUI` and `APPKEY` allow the device to join the LoRaWAN network via OTAA:
 
 ```c
 #define APPEUI                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
@@ -36,9 +36,9 @@ The application behavior can be adjusted by modifying `conf/app_conf.h`.
 #define APPKEY                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
 ```
 
-> **Note:** The default `0x00` is a place holder and you are required to change these values in order to achieve a successful activation. For testing purposes, these values can be random.
+{{< note >}} The default `0x00` is a place holder and you are required to change these values in order to achieve a successful activation. For testing purposes, these values can be random. {{</ note >}}
 
-- `LORAWAN_APPLICATION_TX_INTERVAL_SEC` in seconds defines the transmission interval of the application.
+`LORAWAN_APPLICATION_TX_INTERVAL_SEC` in seconds defines the transmission interval of the application:
 
 ```c
 #define LORAWAN_APPLICATION_TX_INTERVAL_SEC    ( 10U )

diff --git a/doc/content/applications/se-secure-element-lorawan/_index.md b/doc/content/applications/se-secure-element-lorawan/_index.md
@@ -5,5 +5,8 @@ weight: 9
 distributions: null
 ---
 
-This [application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/secure_element_lorawan) showcases LoRaWAN functionality using a HW secure element (ATECC608A-TNGLORA).
+The [secure_element_lorawan application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/secure_element_lorawan) showcases LoRaWAN functionality using a HW secure element (ATECC608A-TNGLORA).
+
+<!--more-->
+
 You can learn more about LoRaWAN and HW secure elements from [here](https://www.thethingsindustries.com/secure-elements/) and [here](https://www.thethingsindustries.com/docs/devices/atecc608a/).
diff --git a/doc/content/applications/se-secure-element-lorawan/configuration.md b/doc/content/applications/se-secure-element-lorawan/configuration.md
@@ -6,16 +6,16 @@ weight: -1
 
 The application behavior can be adjusted by modifying `conf/app_conf.h`.
 
-- `GNSE_ADVANCED_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity
+`GNSE_ADVANCED_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity:
 
 ```c
 #define GNSE_ADVANCED_TRACER_ENABLE 1
 ```
 
-- `DEBUGGER_ON` enables the use of a debugger in low power mode
+`DEBUGGER_ON` enables the use of a debugger in low power mode:
 
 ```c
 #define DEBUGGER_ON       1
 ```
 
-> **Note:** Please keep in mind that it is best to disable the tracer and debugger functionalities to reduce power consumption.
+{{< note >}} Please keep in mind that it is best to disable the tracer and debugger functionalities to reduce power consumption. {{</ note >}}
diff --git a/doc/content/applications/se-sensors-lorawan/_index.md b/doc/content/applications/se-sensors-lorawan/_index.md
@@ -5,4 +5,4 @@ weight: 10
 distributions: null
 ---
 
-This [application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/sensors_lorawan) samples the on-board device sensors information and transmits the sensor data over LoRaWAN.
+The [sensors_lorawan application](https://github.com/TheThingsIndustries/generic-node-se/tree/develop/Software/app/sensors_lorawan) samples the on-board device sensors information and transmits the sensor data over LoRaWAN.
diff --git a/doc/content/applications/se-sensors-lorawan/configuration.md b/doc/content/applications/se-sensors-lorawan/configuration.md
@@ -6,21 +6,21 @@ weight: -1
 
 The application behavior can be adjusted by modifying `conf/app_conf.h`.
 
-- `GNSE_ADVANCED_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity
+`GNSE_ADVANCED_TRACER_ENABLE` enables UART (115200/8-N-1) logging of application activity:
 
 ```c
 #define GNSE_ADVANCED_TRACER_ENABLE 1
 ```
 
-- `DEBUGGER_ON` enables the use of a debugger in low power mode
+`DEBUGGER_ON` enables the use of a debugger in low power mode:
 
 ```c
 #define DEBUGGER_ON       1
 ```
 
-> **Note:** Please keep in mind that it is best to disable the tracer and debugger functionalities to reduce power consumption.
+{{< note >}} Please keep in mind that it is best to disable the tracer and debugger functionalities to reduce power consumption. {{</ note >}}
 
-- `APPEUI`, `DEVEUI` and `APPKEY` allow the device to join the LoRaWAN network via OTAA.
+`APPEUI`, `DEVEUI` and `APPKEY` allow the device to join the LoRaWAN network via OTAA:
 
 ```c
 #define APPEUI                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
@@ -30,15 +30,15 @@ The application behavior can be adjusted by modifying `conf/app_conf.h`.
 #define APPKEY                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
 ```
 
-> **Note:** The default `0x00` is a place holder and you are required to change these values in order to achieve a successful activation. For testing purposes, these values can be random.
+{{< note >}} The default `0x00` is a place holder and you are required to change these values in order to achieve a successful activation. For testing purposes, these values can be random. {{</ note >}}
 
-- `SENSORS_PAYLOAD_APP_PORT` defines LoRaWAN application port where sensors information can be retrieved by the application server.
+`SENSORS_PAYLOAD_APP_PORT` defines LoRaWAN application port where sensors information can be retrieved by the application server:
 
 ```c
 #define SENSORS_PAYLOAD_APP_PORT        2
 ```
 
-- `SENSORS_TX_DUTYCYCLE` in millisecond defines the application data transmission interval.
+`SENSORS_TX_DUTYCYCLE` in millisecond defines the application data transmission interval:
 
 ```c
 #define SENSORS_TX_DUTYCYCLE                            10000