Document update

doc/dev_kits/sufficient_iot_hub/source/quick_start.md

@@ -1,77 +1,133 @@
 # Getting Started
 
 ## Introduction
-Here is a T113 development board with LoRaWAN function.
+[Sufficient IoT Hub](https://heltec.org/project/sufficient-iot-hub/) is an easy to use Linux development board with LoRa, Wi-Fi, Ethernet, etc. functions, It can be used as a quick learning tool and can also be used for professional purposes.
 
+ This document trying to make sense how to getting start with Sufficent IoT Hub development kit.
 
 ## Setting up your Sufficient IoT Hub
 
+### Preparation
+
+- A computer (Windows or Mac).
+- A [Sufficient IoT Hub](https://heltec.org/project/sufficient-iot-hub/).
+- A [TF card](https://heltec.org/product/tf-card/) with 2GB or more.
+- A TF card reader.
+- A [UART-USB bridge](https://heltec.org/product/uart_programmer/) and some wire.
+- A Type C USB cable.
 
-### Make a SD Cards for Sufficient IoT Hub
-1. Download [SD_Card_Toolkit.zip]() and unzip it.  
 
-2. Insert the SD card into the computer with the card reader, and the computer will detect the SD card.        
+### Make a SD Cards for Sufficient IoT Hub
+Download [SD Card Formatter](https://www.sdcard.org/downloads/formatter/) and unzip it.  
 
-3. Find the **SD Card Formatter** tool, double-click to open it, and select the card to be burned for formatting, as shown in the figure.
+Insert the SD card into the computer with the card reader, and the computer will detect the SD card. Open the **SD Card Formatter** tool, and select the card to be burned for formatting, as shown in the figure.
 
-  ![](img/SD_Formatter.png)       
+  ![](img/SD_Formatter.png)
 
-4. Download [T113_sdcard.img]() locally.  
+Download the newest [Sufficient IoT Hub image](https://resource.heltec.cn/download/surficient_iot_hub/t113_img) locally.  
 
-5. Open the tool **Win32DiskImager** just downloaded, and burn it according to the following steps.
+Open the tool [Win32 Disk Imager](https://sourceforge.net/projects/win32diskimager/) just downloaded, and burn it according to the following steps.
 
 ![](img/Win32DiskImager.png)
 
-> Note: SD needs at least 2G capacity, 8G memory card is recommended.
+``` {Note} SD needs at least 2G capacity, 8G memory card is recommended.
+
+```
+
+Take the SD card you just burned and insert it into the Sufficient IoT Hub. Now, the preparation work is completed, the Sufficient IoT Hub is ready for power up.
+
 ### Establish Serial Connection
-1. Take the SD card you just burned and insert it into the development board.
-2. The development board uses serial port 3 (`PB6`, `PB7`) as the debug output serial port, the baud rate of the serial port is 115200, connect the serial port 3 to the computer above the serial software, you can see the printout.
+
+In order to interact with the Sufficient IoT Hub, a serial port connection may need to be established during initial startup.
+
+The Sufficient IoT Hub uses T1113's serial port 3 (`PB6`, `PB7`) as the debug serial port, the baud rate of the serial port is `115200`. Connect wire between Sufficient IoT Hub and [USB-UART Bridge](https://heltec.org/product/uart_programmer/) as follows sequence:
+
+```
+Sufficient IoT Hub PB6(TX) -- USB-UART Bridge RX
+Sufficient IoT Hub PB7(RX) -- USB-UART Bridge TX
+Sufficient IoT Hub GND     -- USB-UART Bridge GND
+```
+
+Connect USB-UART Bridge to your computer and power ON Sufficient IoT Hub.
+
+```{Note} The Heltec USB-UART Bridge use CH340 chip, computer deivers may beed to be installed.
+
+```
+
+#### For Mac 
+
+You can use embed `screen` tools: `screen /dev/cu.usbserial-xxx 115200`.
+
+`cu.usbserial-xxx` is the the seral port number of USB-UART Bridge. If the driver is installed correctly, you can find it via `ls /dev/cu.*`.
+
+#### For Windows
+
+You may need a seral port read tools like [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html).
+
+![](img/13.png)
+
+`COM10` is the the seral port number of USB-UART Bridge. If the driver is installed correctly, you can find it in your computer's device manager.
+
+![](img/shell.png)
+
 ### Login Sufficient IoT OS
-1. You can see the login screen on top of the serial software.
-> Username: root
-> Password: 123456.
+You can see the login screen on top of the serial software.
+
+Username: `root`
+Password: `123456`
 
 ## Configuration
 
-### Manually connect to WiFi
+### Manually connect to Wi-Fi
+
+Switch into the `/etc` directory via `cd /etc` command.
+
+Use the following statement for networking.
 
-1. Go under the **/etc** directory.
-2. Use the following statement for networking.
 ```sh
-bash wlan-connect.sh yourssid  yourpwssd   1
+bash wlan-connect.sh yourssid yourpwssd 1
 ```
-### Automatically connect to WiFi
+### Automatically connect to Wi-Fi
 
-  After the first configuration, it will automatically connect every time it is turned on, and there is no need to configure it again.
+With the following configuration, system will automatically connect to Wi-Fi when it is turned on.
 
-1. Configure the ssid and password of WiFi.
+Configure the ssid and password of WiFi.
 
 ```sh
-wpa_passphrase  SSID  Password  > /etc/wpa_supplicant/user_wifi.conf 
+wpa_passphrase SSID Password > /etc/wpa_supplicant/user_wifi.conf 
 ```
 
-2. Restart the service for networking
+Restart the service for networking
 
 ```sh
 reboot
 ```
 
 ### Ethernet Connection
 
-1. You need to plug in the Internet cable first.
-2. Execute the following statement to connect to the Internet.
+You need to plug in the Internet cable first.
+
+Execute the following statement to connect to the Internet.
+
 ```sh
 udhcpc -i eth0
 ```
-### Illuminate the white light
-1. Execute the following statement in any directory:
+
+
+### Some functional tests
+
+#### Illuminate the white LED
+
+Execute the following statement in any directory:
+
 ```sh
  echo 113 > /sys/class/gpio/export
  echo out > /sys/class/gpio/gpio113/direction
  echo 1 > /sys/class/gpio/gpio113/value
 ```
-### I2C scanning
-1. If an I2C device is connected, its address will be displayed in the scan.
+#### I2C scanning
+If an I2C device is connected, its address will be displayed in the scan.
+
 ```sh
 echo 1 > /proc/sys/kernel/printk
 i2cdetect -y -r 2

doc/dev_kits/sufficient_iot_hub/source/sufficient_iot_application.md

@@ -1,68 +1,113 @@
 # Sufficient IoT Application
 
-
 ## Introduction
 
+The [Sufficient IoT Application](https://github.com/HelTecAutomation/Sufficient-IoT-Application) is a specially designed application for LoRa/LoRaWAN, it will greatly facilitate users to learn and use LoRa technology.
+
 
 ## Use the Sufficient IoT Application
 
 ### Configuration
-1. Go to the **. /home/lora/linux_lora/build** directory and execute the following statement, which will generate the executable **demo** under the **/home/lora/linux_lora/bin** path, the executable file **demo** will be created.
+Go to the `/home/lora/linux_lora/build` directory and execute the following statement, which will generate the executable demo under the `/home/lora/linux_lora/bin` path, the executable file **demo** will be created.
+
 ```
 cmake ..
 make clean
 make 
 ```
-#### LoRaWAN Parameter Configuration
-1. In **/home/lora/linux_lora/build** , use the following statement to enter the configuration interface, you can configure the parameters of LoRaWAN.
+### License Validation
+
+When running for the first time, or change a TF card running system, you may need a license to activate the device.
+
+Enter the folder of LoRaWAN executable files.
+
+```sh
+cd /home/lora/linux_lora/bin/
+```
+
+Execution `./demo`
+
+```shell
+Certificate verification failed
+Please provide a correct license! For more information:
+http://www.heltec.cn/search/
+ChipID=303030303337
+```
+
+Open the [address](https://resource.heltec.cn/search) connection to obtain the license, enter the **ChipID** of the product obtained in the previous step, and you can obtain the required license.
+
+![](img/10.png)
+
+Use the shell command `make menuconfig` to open the configuration interface, find the license input option, and enter the aforementioned license. Save and exit.
+
+![](img/09.png)
+
+### LoRaWAN Parameter Configuration
+
+When the Sufficient IoT Application is correctly compiled and lincese actived, use the following statement to enter the configuration interface, you can configure the parameters of LoRaWAN.
+
 ```
+cd /home/lora/linux_lora/build
 make menuconfig
 ```
-2. The interface is as follows:
-![](img/lora_config.jpg)
-3. Here you can configure various parameters of lorawan, such as: front channel code, EUI, appkey, etc.
+Then you will see a menu like this:
+![](img/11.png)
+
+In the configure menu, there are following options can be set:
+
+- **LORAWAN_REGION** -- LoRaWAN protocol region definition, strictly follow [LoRaWAN™ 1.0.2 Regional Parameters rB](https://resource.heltec.cn/download/LoRaWANRegionalParametersv1.0.2_final_1944_1.pdf).
+- **LORAWAN_CLASS** -- Now with `Class A` and `Class C` supported.
+- **LoRaWAN preamble length** -- LoRaWAN preamble length can be set to `8` or `16`.
+- **LoRaWAN network access method** -- `OTAA` or `ABP`, parameters such as EUI and AppKey in their sub options.
+- **LoRaWAN debug level** -- Print uplink/downlink frequency, DIO, error messages.
+- **LoRaWAN upload data** -- Custom data or predefined sensor data be sent in LoRaWAN format.
+- **LoRaWAN channels mask** -- The maximum number of channels used in LoRaWAN communication is **8**, and the channels must be continuous, such as 0~7,  8~15. For the definition of LoRaWAN channels, please refer to [LoRaWAN™ 1.0.2 Regional Parameters rB](https://resource.heltec.cn/download/LoRaWANRegionalParametersv1.0.2_final_1944_1.pdf).
+- **LoRaWAN duty cycle** -- The time interval between each two transmit data.
+- **LoRaWAN app port** -- Default app port.
+- **LoRaWAN other options configuration** -- Enable/disable `ADR` and `Confirmed data` functions.
 
-#### Sensor Configuration
-1. In the ***LoRaWAN upload data selection*** option, the data from the optional sensors can be uploaded.
-2. The following sensors are currently available：
-![](img/sensor.jpg)
-3. If you choose the I2C sensor, then you need to connect the corresponding sensor to TWI2_SDA and TWI2_SCK.![](img/t113_pin.jpg)
+#### Send custom test data via LoRaWAN
 
-### Usage Example
-1. Configure the frequency band, APP_KEY, APP_EUI, APP_KEY, how to configure see LoRaWAN Parameter Configuration.   
-2. Select bmp180 sensor：   
-![](img/bmp180.jpg)   
-3. Go to the **/home/lora/linux_lora/bin** folder and execute **./demo** to upload the sensor data.
+In the `LoRaWAN upload data selection` option, `fixed data` can set some custom data to be sent in LoRaWAN format as test.
 
+![](img/12.png)
 
+#### Or send predefined sensor data via LoRaWAN
 
-## License Validation
+```{Note} This part must work with an external sensor.
+
+```
 
-1. Enter the folder of LoRaWAN executable files.
+In the `LoRaWAN upload data selection` option, the data from the optional sensors can be uploaded.
 
-   ```sh
-   cd /home/lora/linux_lora/bin/
-   ```
+The following sensors are currently available：
 
-2. Execution ./demo
+- HDC1080 temperature and humidity sensor
+- BMP180 air pressure and temperature sensors
 
-   ```c
-   Certificate verification failed
-   Please provide a correct license! For more information:
-   http://www.heltec.cn/search/ 
-   ChipID=303030303337   
-   ```
+At present, all predefined sensor are I2C sensor, then you need to connect the corresponding sensor to `TWI2_SDA` and `TWI2_SCK`.![](img/08.png)
 
-3. Open the [address](https://resource.heltec.cn/search) connection to obtain the license, enter the **ChipID** of the product obtained in the previous step, and you can obtain the required license.
+[Sufficient IoT Hub Pinmap](https://resource.heltec.cn/download/surficient_iot_hub/Sufficient_IoT_Hub_Pinmap.pdf)
 
-4. Use the shell command **make menuconfig** to open the configuration interface, find the license input option, and enter the aforementioned license. Save and exit.
+### Running the Application
 
-   ```sh
-   HelTec LoRaWAN license --->
-   ```
+After configuration is completed, use the following commands to run the Sufficient Iot Application:
+
+```shell
+cd /home/lora/linux_lora/bin/
+./demo
+```
+
+```{Tip} Configuration parameters must be in path "/home/lora/linux_lora/build", and the running the Sufficient Iot Application must be in path "/home/lora/linux_lora/bin/".
+
+```
 
 ## Source Code
 
+In the downloadable firmware, there already have a Sufficient IoT Application package in the `/home/lora/linux_LoRa` path. But it may not be the latest version, you can obtain the latest version of the code in GitHub:
+
+https://github.com/HelTecAutomation/Sufficient-IoT-Application
+
 ### The development frame work
 
 #### The basic structure of the project
@@ -86,7 +131,7 @@ make menuconfig
 ```
 
 ---------------------------------------
-####  Currently supported bands
+####  Currently supported LoRaWAN bands
  >- [x] AS923 region
  >- [x] AU915 region
  >- [x] CN470 region
@@ -102,8 +147,9 @@ make menuconfig
  >- [x] AS923 AS2 region
 
 ---------------------------------------
-#### Add your own functional modules
+### Add your own functional modules
 **Take bmp180 as an example**
+
 1. Add a new folder with the file name bmp180 to the functional_module folder.
 2. Add the following file to the bmp180 folder    
 > bmp180.c     
@@ -143,12 +189,14 @@ target_link_libraries(${PROJECT_NAME} fifo config lora hdc1080 bmp180 data_conve
 
 ---------------------------------------
 #### Add graphical configuration interface options
-1. Find the project's Kconfig file, and in the LORAWAN_APP_DATA menu bar, add
+Find the project's Kconfig file, and in the LORAWAN_APP_DATA menu bar, add
+
 ```kconfig
 config BMP180_DATA
     bool "bmp180"
 ```
-2. In the LORAWAN_DATA_SELECTION menu bar of project/config/config.ini, add
+In the LORAWAN_DATA_SELECTION menu bar of project/config/config.ini, add
+
 ```ini
 ;BMP180_DATA=3
 ```
@@ -163,17 +211,19 @@ typedef enum
     bmp180_data
 }data_selection_num;
 ```
-3.  In project/config/kconfig_lib/configini_to_kconfig.sh  #Configure LoRaWAN upload data selection add
+In project/config/kconfig_lib/configini_to_kconfig.sh  #Configure LoRaWAN upload data selection add
+
 ```sh
 elif [ $DATA_SELECTION -eq 3 ];then
     echo "CONFIG_BMP180_DATA=y" >> $K_CONFIGFILE
 ```
 - The above sentence indicates that the C configuration file is synchronized with the GUI configuration file.
 
-4. Add read config.ini file to project/main/main.c.
+Add read config.ini file to project/main/main.c.
+
 ```c
     data_selection = iniparser_getint(ini,"LORAWAN_DATA_SELECTION:data_selection",-1);
 ```
-5. Use make menuconfig to configure the bmp180 option and save it, then read out data_selection = 3 in main.c.
+Use make menuconfig to configure the bmp180 option and save it, then read out data_selection = 3 in main.c.
 
-6. Once added, you can go through the options in man.c to implement the relevant functions.
+Once added, you can go through the options in man.c to implement the relevant functions.