TencentOS-tiny/doc/26.TencentOS_tiny_EVB_WL_Quick_Start.md

# TencentOS tiny定制开发板EVB_WL快速入门指南

| Revision | Date      | Description |
| -------- | --------- | ----------- |
| 1.0      | 2020-7-28 | 文档初版    |

## 1. 定制开发板EVB_WL硬件简介

### 1.1 开发板简介

EVB_WL是腾讯物联网操作系统TencentOS tiny 团队联合意法半导体、瑞兴恒方、智芯云技术设计的一款loRaWAN OpenCPU评估板，用于TencentOS tiny 基础内核和LoRaWAN物联网组件功能体验和评估。
开发板功能图如下所示：
![](image/EVB_WL_guide/EVB_WL.png)

### 1.2 开发板特性
**CPU** ：使用瑞兴恒方的RHF0M0E5模组，模组内部集成意法半导体STM32WLE5芯片，单芯片集成ARM® Cortex®-M4 48MHz内核和SX126x IP；采用LoRa®扩频调制技术，LoRa®接收灵敏度高达-148dBm，通信距离达1KM～10KM；内置高效率PA，功耗更低，最大支持+22dBm输出，并在0-22dBm范围内可配置。

**电源特性** ：Micro USB接口，5V供电，内部有5V转3.3V的DCDC，MCU供电电压为3.3V，系统IO电压也为3.3V

**按键** ：一个复位按键


**LED指示灯** ：上电指示 LED，红色；

**调试接口** ：SWD外接ST-Link，UART1串口连接PC/LUART串口


**传感器扩展接口E53 Interface** ：支持E53传感器案例扩展板（支持UART、SPI、IIC、GPIO、ADC、DAC等）


**操作系统支持** ：TencentOS tiny



### 1.3 开发板硬件详解

#### 1.3.1 电源电路
Micro USB 提供5V电源，由于MCU供电电压是3.3V，所以这里采用AMS1117进行DC-DC电压转换，输出调节至3.3V，让开发板正常工作。
![](image/EVB_WL_guide/power_sch.png)

#### 1.3.2  CPU最小系统电路
单片机最小系统或者叫最小硬件单元电路，指用最少元器件组成的单片机可以正常工作的系统。最小系统基本由电源、单片机、晶振、复位电路、程序烧录接口组成，电源使用3.3V直接供电，但是EVB_WL的晶振电路封装在瑞兴恒方模组内部了，所以这里只能看到模组引脚连接和复位电路，原理图如下：
![](image/EVB_WL_guide/mcu_sch.png)

#### 1.3.3  USB电平转换电路
USB电平转换电路是用于MCU和PC通信的场景中。PC机上的通信接口使用USB接口，相应的电平逻辑需要遵照USB电平规则，而MCU的串行通信接口是串口，相应电平需要遵循TTL原则。为了使两者可以互相通信，就需要一个电平转换器，EVB_WL上使用了CH340芯片作为转换器，CH340外围只需要接很少的元器件即可以实现USB总线转接，使用非常方便也广泛运用在USB转TTL工具上，电路如下：

![](image/EVB_WL_guide/uart_sch.png)

#### 1.3.4 E53 传感器扩展接口
开发板设计有E53接口的传感器扩展板接口，该接口可兼容所有E53接口的传感器扩展板，实现不同物联网案例场景的快速搭建。该接口可接入UART、SPI、I2C、ADC等通信协议的传感器，其原理图如下图所示。
![](image/EVB_WL_guide/e53_interface.png)

传感器扩展板有E53_SC1智慧城市灯光模块、E53_SF1智慧消防烟感模块、E53_IA1智慧农业模块等，如需要更多传感扩展板可自行找合作供应商（物联网俱乐部）购买）。
如下图：
![](image/EVB_WL_guide/sensor_install.png)

#### 1.3.5 开发板调试烧录口
开发板预留了SWD程序下载调试口，还有UART1和低功耗串口LP_UART，方便用户下载调试程序，使用串口。
![](image/EVB_WL_guide/debug_sch.png)


#### 1.3.6  连接Micor USB线
Micro USB线的功能是供电及调试，将线一头与开发板的Micro接口连接，另一头接到电脑的USB口上。
![](image/EVB_WL_guide/usb_connect.png)

#### 1.3.7  连接ST-Link程序下载器
把开发板内提供的配套下载线接在开发板的程序下载接口（SWD口），另一端与ST-Link程序下载器对应引脚相连，注意连接紧密，防止接触不良，红色为VCC，一定参考下图进行连接，不要接错。
![](image/EVB_WL_guide/stlink-connect.png)

## 2. 定制开发板EVB_WL软件开发环境准备

### 2.1 MDK软件介绍
MDK 即RealView MDK 或MDK-ARM（Microcontroller Development kit），是 ARM 公司收购Keil公司以后，基于uVision界面推出的针对ARM7、ARM9、Cortex-M0、Cortex-M1、Cortex-M2、Cortex-M3、Cortex-R4等ARM处理器的嵌入式软件开发工具。MDK-ARM 集成了业内最领先的技术，包括 uVision4 集成开发环境与 RealView 编译器RVCT。支持 ARM7、ARM9 和最新的Cortex-M3/M1/M0 核处理器，自动配置启动代码，集成 Flash 烧写模块，强大的 Simulation 设备模拟，性能分析等功能，与 ARM 之前的工具包 ADS 等相比，RealView 编译器的最新版本可将性能改善超过 20%。
Keil公司开发的ARM开发工具MDK，是用来开发基于ARM核的系列微控制器的嵌入式应用程序。它适合不同层次的开发者使用，包括专业的应用程序开发工程师和嵌入式软件开发的入门者。MDK包含了工业标准的Keil C编译器、宏汇编器、调试器、实时内核等组件，支持所有基于ARM的设备，能帮助工程师按照计划完成项目。

### 2.2 MDK安装
登录MDK官网，下载MDK5软件，下载地址：
http://www2.keil.com/mdk5  或者 https://www.keil.com/download/product/
下载的版本最好在5.24以上，本开发教程以5.24版本为例，双击MDK524应用程序文件，点击next>>。

![](image/EVB_WL_guide/mdk01.png)

打上 I agree前面的勾勾，即是同意一些安装协议。点击next>>。

![](image/EVB_WL_guide/mdk02.png)

选择安装路径，可以默认也可以安装在我们自己建立的文件夹下。点击next>>。

![](image/EVB_WL_guide/mdk03.png)

这里填写的是我们的一些信息，填写完整后，继续next>>。

![](image/EVB_WL_guide/mdk04.png)

然后等待安装完成即可。

![](image/EVB_WL_guide/mdk05.png)

安装完成，点击Finish。

![](image/EVB_WL_guide/mdk06.png)

然后会跳出来这个界面，这个我们后面再讲，先点OK，把弹框都叉掉。

![](image/EVB_WL_guide/mdk07.png)

激活MDK，导入License,激活MDK后便可使用了。

![](image/EVB_WL_guide/mdk08.png)
![](image/EVB_WL_guide/mdk09.png)

特别提示：一定要输入License激活MDK软件，建议购买正版License。

### 2.3 MDK安装
安装完MDK后，我们需要安装开发套件中单片机型号对应的Pack。
**安装方式一**  登录官网：http://www.keil.com/dd2/pack/ 
下载Keil.STM32WLxx_DFP.1.0.0.pack 后安装，如下图

![](image/EVB_WL_guide/mdk_pack01.png)

**安装方式二**  MDK软件上在线安装

打开软件，在导航栏打开Pack安装界面，然后选择ok选项。

![](image/EVB_WL_guide/mdk_pack02.png)
![](image/EVB_WL_guide/mdk_pack03.png)

进入在线安装界面，选着STM32WLXX Pack,点击Install进行安装。

![](image/EVB_WL_guide/mdk_pack04.png)

至此，我们开发板的单片机程序开发环境已经搭建完毕，重启MDK软件就可以使用了。

### 2.4 ST-Link驱动安装
前面讲了开发板单片机程序的开发环境的搭建，但是为了将程序烧录到开发板中我们还需要使用仿真器。我们这套开发板选用ST公司的ST-Link V2仿真器进行开发板程序的烧写和仿真，下面介绍ST-Link驱动的安装及环境搭建。
在ST官网下载ST-Link驱动，
https://www.st.com/content/st_com/zh/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-utilities/stsw-link009.html

（驱动有2种： 32位电脑系统安装“dpinst_x86”、64位电脑系统安装“dpinst_amd64”）。 

![](./image/EVB_WL_guide/development_env_stlink_driver_file.png)

运行对应的驱动，安装ST-Link V2驱动程序。安装路径尽量保持默认路径。

![](./image/EVB_WL_guide/development_env_stlink_driver_install.png)

安装完成后, 将ST-Link通过USB接口连入电脑。打开“设备管理器”。若看到如下图所示，表示驱动安装成功。

![](./image/EVB_WL_guide/development_env_stlink_driver_ok.png)

这里提醒 2 点:
1，	各种 windows 版本设备名称和所在设备管理器栏目可能不一样，例如 WIN10 插上STLINK 后显示的是 STM32 STLINK。
2，	如果设备名称旁边显示的是黄色的叹号，请直接点击设备名称，然后在弹出的界面点击更新设备驱动
至此， ST-Link 驱动已经安装完成。接下来大家只需要在 MDK工程里面配置一下 ST-Link即可。

### 2.5  编程软件(MDK)配置
安装驱动成功后，打开MDK软件，配置程序烧写和仿真的环境。
点击进入工程配置界面按纽，进入工程配置界面。

![](./image/EVB_WL_guide/development_env_mdk_config_click.png)

选择Debug选项，进入仿真器设置界面。

![](./image/EVB_WL_guide/development_env_mdk_config_debug.png)

下拉仿真器选择列表，选着ST-Link Debugger并勾选右侧Use,点击Settings进入ST-Link V2仿真器配置界面。

![](./image/EVB_WL_guide/development_env_mdk_config_debugger.png)

开发板设计的程序烧录方式为SW，此处Unit选择ST-Link/V2,且Port选择SW,并确认右侧框内是否检测出SW设备，点击<确认>保存配置。

![](./image/EVB_WL_guide/development_env_mdk_config_debugger_setting.png)

### 2.6  CH340串口驱动安装

互联网搜索下载CH340 串口芯片的驱动
安装方法：打开驱动安装程序点击安装即可。

![](./image/EVB_WL_guide/ch340_file.png)
![](./image/EVB_WL_guide/ch340_driver_install.png)

注：若安装失败，请先点击卸载，后点击安装。

### 2.7 串口调试助手的安装与使用

工具下载： http://www.daxia.com/download/sscom.rar

安装方法：串口调试助手sscom5.13.1是免安装的，解压出压缩包即可直接使用。

![](./image/EVB_WL_guide/development_env_sscom.png)

根据PC和终端之间的连接，选择正确的串行端口。
打开电脑的设备管理器，在端口列表可以看到PC与开发板连接的端口号。

![](./image/EVB_WL_guide/development_env_sscom_port.png)

我这里显示的是COM6，所以要在sscom工具中选择COM6，开发板程序波特率设置为115200，所以我在sscom串口工具中选择115200波特率。

## 3. 基于TencentOS tiny的STM32WL LoRaWAN 接入腾讯云IoT Explorer指引 

基于TencentOS Tiny EVB WL要完成腾讯云IoT Explorer对接，需要完成两个部分的工作。
一是：腾讯云IoT explorer 上完成项目、产品、设备创建、参数配置
二是：基于TencentOS Tiny完成LoRaWAN应用开发，向腾讯云上报业务数据。

### 3.1  腾讯云IoT explorer上创建项目、产品、设备

#### 创建项目和产品
1. 登录 [物联网开发平台控制台](https://console.cloud.tencent.com/iotexplorer)，选择【新建项目】。
2. 在新建项目页面，填写项目基本信息后，单击【保存】
    - 项目名称：输入“LoRa 温湿度演示”或其他名称。
    - 项目描述：按照实际需求填写项目描述。
3. 项目新建成功后，即可新建产品。
![](./image/EVB_WL_guide/IoT_Explorer_new_project.png)


#### 新建产品
1. 进入该项目的产品列表页面，单击【新建产品】。
2. 在新建产品页面，填写产品基本信息。
    - 产品名称：输入“LoRa温湿度监测仪”或其他产品名称。
    - 产品类型：选择“用户自定义”。
    - 设备类型：选择“设备”。    
    - 认证方式：选择“密钥认证”。
    - 通信方式：选择“LoRaWAN”。
    - 数据协议：选择“自定义透传”。
![](./image/EVB_WL_guide/IoT_Explorer_new_product.png)
3. 产品新建成功后，您可在产品列表页查看“LoRa温湿度监测仪”。

#### 创建数据模板

单击产品名称，进入产品配置页，在【自定义功能】配置项下，单击【新建功能】，自定义产品功能。

这里我们就不一一定义数据模板了，直接导入下面的json代码:

```
{
  "version": "1.0",
  "profile": {
    "ProductId": "F2G256SY2G",
    "CategoryId": "1"
  },
  "properties": [
    {
      "id": "temperature",
      "name": "温度",
      "desc": "",
      "mode": "r",
      "define": {
        "type": "int",
        "min": "-100",
        "max": "155",
        "start": "0",
        "step": "1",
        "unit": "摄氏度"
      },
      "required": false
    },
    {
      "id": "humidity",
      "name": "湿度",
      "desc": "",
      "mode": "rw",
      "define": {
        "type": "int",
        "min": "0",
        "max": "100",
        "start": "0",
        "step": "1",
        "unit": "%"
      },
      "required": false
    },
    {
      "id": "period",
      "name": "上报周期",
      "desc": "",
      "mode": "rw",
      "define": {
        "type": "int",
        "min": "0",
        "max": "3600",
        "start": "0",
        "step": "1",
        "unit": "秒"
      },
      "required": false
    }
  ],
  "events": [],
  "actions": []
}
```



![](./image/EVB_WL_guide/IoT_Explorer_new_data_template.png)

导入完成后，如下图所示：
![](./image/EVB_WL_guide/IoT_Explorer_new_data_template01.png)

#### 配置 LoRaWAN 参数

在设备开发页面中，按需调整 LoRaWAN 参数配置。本示例中使用默认的 OTAA 配置。
![](./image/EVB_WL_guide/IoT_Explorer_product_LoRa_PramSet.png)

#### 设备数据解析
在设备开发页面中，按需调整设备数据解析。由于 LoRa 类资源有限设备不适合直接传输 JSON 格式数据，使用“设备数据解析”可以将设备原始数据转化为产品 JSON 数据。

##### 设备数据协议
在本示例中，设备上行数据共有3个，包括温度、湿度、上报周期3个属性数据
##### 数据解析脚本
上行数据解析的脚本主函数为 RawToProtocol，其带有 fPort、bytes 两个入参：
- fPort：设备上报的 LoRaWAN 协议数据的 FPort 字段。
- bytes：设备上报的 LoRaWAN 协议数据的 FRMPayload 字段。

脚本主函数的出参为产品数据模版协议格式的对象。

在上行数据解析部分，javascript 示例代码如下：
```javascript
function RawToProtocol(fPort, bytes) {
    var data = {
        "method": "report",
        "clientToken" : new Date(),
        "params" : {}
    };
    data.params.temperature = bytes[0];
    data.params.humidity = bytes[1];
    data.params.period = bytes[2] | (bytes[3] << 8);
    return data;
}
```

下行数据解析的脚本主函数为 ProtocolToRaw，其入参为产品数据模版协议格式的对象。

在下行数据解析部分，javascript 示例代码如下：
```javascript
function ProtocolToRaw(obj) {
    var data = new Array();
    data[0] = 5;// fport=5
    data[1] = 0;// unconfirmed mode
    data[2] = obj.params.period & 0x00FF;
    data[3] = (obj.params.period >> 8) & 0x00FF;
    return data;
}
```

![](./image/EVB_WL_guide/IoT_Explorer_new_product_script.png)



#### 创建测试设备

在设备调试页面中，单击【新建设备】，设备名为 WL_DEV_001。

DevEUI、APPKEY等信息可从 WL 开发板 终端设备获取或者设置，云平台和终端要保持一致。


![](./image/EVB_WL_guide/IoT_Explorer_new_dev.png)

####  查看设备状态

1. 保持 LoRa 节点和 LoRa 网关 为运行状态。
2. 进入【控制台】>【产品开发】>【设备调试】，可查看到设备 "WL_DEV_001" 。
3. 单击【调试】，可进入设备详情页。
![](./image/EVB_WL_guide/IoT_Explorer_dev_status.png)
4. 单击【设备属性】，可查询设备上报到开发平台的最新数据及历史数据。
 - 设备属性的最新值：会显示设备上报的最新数据。
 - 设备属性的更新时间：显示数据的更新时间。
![](./image/EVB_WL_guide/IoT_Explorer_dev_data.png)
5. 单击【查看】，可查看某个属性的历史上报数据。

#### 查看设备通信日志

单击【设备日志】，可查询该设备某段时间范围的所有上下行数据。
 - 上行：上行指设备端上报到开发平台的数据。
 - 下行：下行指从开发平台下发到设备的数据。
![](./image/EVB_WL_guide/IoT_Explorer_dev_data_log.png)


### 3.2 基于TencentOS Tiny EVB_WL开发板完成LoRaWAN应用开发

####  下载源码
TencentOS tiny官方开源仓下载源码，地址为：
https://github.com/Tencent/TencentOS-tiny

进入 < TencentOS-tiny\board\RHF0M0E5_STM32WLE5xx\KEIL\lorawan> 目录，打开TencentOS_tiny.uvprojx工程：

![](./image/EVB_WL_guide/MDK_LoRa_Project_open.png)

####  编译lorawan工程

打开工程后，我们在左侧的工程文件导航页面可以看到WL的LoRaWAN相关源码，这里创建了两个TencentOS tiny的任务，一个负责处理LoRaWAN MAC层协议，一个处理业务。开发者在编译前需要配置设备相关信息。
打开commissioning.h头文件，在文件中输入与前文IoT Explorer平台对应的device EUI和APP KEY，按如下图所示的格式：
![](./image/EVB_WL_guide/LORA_EUI_KEY.png)

基于TencentOS Tiny的WL开发板的业务流程如下：
1. main函数中完成 板级初始化，主要是 board_init函数中初始化好基础外设和LoRa射频及LoRa协议栈；其中MX_LoRaWAN_Init函数会完成LoRaWAN协议的基础配置，比如选择CLASS、配置通道、配置ADR等；
2. main函数中，完成内核初始化、创建主线程入口application_entry，启动内核；
3. application_entry函数中再创建lora_mac_process_task；
4. application_entry函数中调用lw_send函数向LoRa网关和云端上报终端数据。示例中是模拟了3个元数据发送，开发者可以修改发送自己想发送的数据，配合腾讯云IoT平台设计好对应的数据模板即可。

修改设备信息后，开发者按照下图指示，点击编译按钮即可编译工程，如图：

![](./image/EVB_WL_guide/MDK_Complie.png)

#### 下载运行

首先需要配置下载环境

![](./image/EVB_WL_guide/MDK_settings.png)

按下图所示配置下载参数

![](./image/EVB_WL_guide/download_debug.png)

![](./image/EVB_WL_guide/download_flash.png)

编译完成后点击如图所示”LOAD”按钮下载程序即可。

![](./image/EVB_WL_guide/download_go.png)

#### 查看运行结果

连接好串口，在PC的串口助手中可以看到TencentOS Tiny EVB_WL开发板打印LoRa业务运行的相关日志，如下图所示：

![](./image/EVB_WL_guide/lorawan_ok.png)

同时需要查询腾讯云IoT Explore上的设备状态和上报的数据项，如图所示：

![](./image/EVB_WL_guide/WL_LoRa_Data.png)


写在结尾的话：感谢大家使用TencentOS Tiny，本文难免有描述不清晰的地方，如果有任何问题，欢迎加入TencentOS Tiny 的官网QQ技术群进行交流，基于TencentOS Tiny相关的项目合作请邮件联系 supowang@tencent.com

![](./image/EVB_WL_guide/TencentOS_Tiny_qq.png)