MCU SDK
更新时间：2018-02-07 09:51:46
简介
由于低配置且资源受限或者对网络流量有要求的设备不适合直接构造JSON数据和云端通信，因此选择通过二进制方式透传到云端，由云端运行转换脚本将透传的数据转换成自己可以理解的Alink格式的JSON数据。目前转换脚本通过JS开发，设备和脚本间数据协议格式支持标准和自定义的方式。使用标准协议开发的设备可以直接使用云端自动生成的脚本，如果协议自定义则需要开发者自行开发JS脚本。
针对上述提到的二进制的标准协议，我们提供了MCU SDK实现了协议的封装。此外，我们还会根据开发者的产品功能定义在MCU SDK中生成与之对应的代码和上报、接收处理逻辑。开发者使用MCU SDK开发就不用实现通讯协议和产品功能的定义，直接按照提供的API接口调用或添加自己的业务逻辑即可。
比如云端下发一个关灯（对应属性标识Switch）的请求，需要在开发者在特定的API内部实现Switch的处理，MCU SDK默认实现了对云端的回复；比如设备本地灯的开关状态变化，开发者的程序识别到后调用修改Switch属性的API后，MCU SDK会自动将变化上报到云端。这样开发者就只需要关注设备业务功能的开发即可。
获取方法
采用透传数据格式的设备，支持选择不同的硬件平台自动生成相应的MCU SDK，开发者可以按需下载。
初始状态下，MCU SDK显示未生成，开发者需要点击生成，选择相应的硬件平台。后续我们将陆续支持更多的硬件平台。
选择硬件平台进行生成：
生成后可以直接点击下载SDK。特别说明，如果产品功能定义有修改，需要重新生成sdk后再下载。
根据芯片生成的SDK说明
目前MCU SDK支持如下几种芯片型号生成对应开发工程，开发者可以直接基于此工程直接开发自己的应用。如果选择其他平台，我们只提供sdk和简单的示例demo，开发者可以在Linux进行编译运行。
STM8S207
开发IDE使用IAR for STM8（EWSTM8）。参考生成的SDK中的Readme.txt。STM32L053R8
开发IDE使用Keil MDK5。参考生成的SDK中的Readme.txt。其他平台
仅提供简单的示例。可以在Linux中编译运行。
（a）编译方法：进入sample目录，执行make。
（b）运行方法：./a.out。运行后支持输入的命令格式：set 属性名称=属性值。
比如修改设备的调光等级(对应属性标识LightAdjustLevel)可以执行set LightAdjustLevel=100。运行命令设置属性后会打印出生成的二进制数据，参考如下：
注意：如上命令目前只支持基本类型的属性上报数据生成，对于复杂类型的属性或者事件暂不支持。
目录结构说明
MCU SDK的目录结构如下图所示，包括了头文件目录inc和源代码目录src。
头文件
bonedevice_common.h
SDK共用的头文件，包括了类型定义、SDK全局对象定义以及公共的API。需要开发者关注。bonedevice_platform.h
定义了需要开发者实现或者处理的函数。需要开发者关注。bonedevice_protocol.h
定义了和云端通讯协议的使用的接口。开发者可以不用关注。bonedevice_thing.h
包含了产品功能(属性、服务、事件)相关定义。需要开发者关注。
thing.h和thing.c会根据产品的TSL自动生成。
源文件
bonedevice_common.c
SDK公共代码的实现。bonedevice_protocol.c
和云端通信协议的定义及接口实现。bonedevice_thing.c
产品功能相关的接口实现。
thing.h和thing.c会根据产品的TSL自动生成。
API说明
需要用户调用的接口
公共接口
/ SDK初始化函数 /
void boneSdkInit(void);
/ SDK运行函数，在while中调用 /
void boneSdkRun(void);
/ 接收串口的字节数据，在串口中断服务程序中调用 /
int32 boneRecvFromUart(int8 val);
/ 系统运行时间计算(定时1ms调用)，暂时可以不用实现 /
void boneSystimeInc(void);
产品功能相关接口
/ 属性值范围定义 /
#define ATTR_XXX
/ 属性值的设置和获取，AttrName表示的是属性名称，实际的接口名称和属性标识对应，AttrVal表示的是属性的值， ValueType表示的是属性的类型 /
void boneSet_AttrName(AttrVal);
ValueType boneGet_AttrName(void);
/ 事件上报，EventName表示的是事件名称，实际的接口名称和事件标识对应，Params表示事件的输出参数 /
void boneEvntPost_EventName(Params);
注意：以上接口及参数定义的只是一个模版，具体的API要视自己定义的产品功能而定。以下是示例产品自动生成的API。
属性值范围定义：
属性值的设置和获取：
事件上报：
需要用户实现的接口
/ 串口发送协议数据 /
int32 boneUartSend(uint8*frame, uint16 length);
/ 时间记录到时钟芯片。如果不支持可以空实现 /
int32 boneWriteRtc(uint8*time, uint8 len);
/ 固件更新。如果不支持可以空实现 /
int32 boneFirewareUpdate(uint8*buf, uint32 length);
需要用户添加处理方法的接口
/ 处理因服务端修改的属性变化的情况 /
void boneHandleAttrChange(uint8 attrId);
/ 服务处理函数，如果没有服务可忽略。接口名称中的ServiceName表示的是服务名称，实际的接口名称和服务标识对应 */
int32 boneHandleSrv_ServiceName(Params);
示例产品上定义的服务的处理函数：
通讯协议
基本通讯格式定义
如下是制定的厂商MCU和无线模组（或服务端）通讯的协议帧格式：
使用说明：
- 本文档对通信方式和物理参数不做要求，由通讯双方自行协商
比如：UART通信，需要指定如下参数：
波特率：115200
数据位：8
奇偶校验：无
停止位：1
数据流控：无
数据传输统一使用大端（高字节在前，低字节在后）字节序
为保证传输可靠性，通信需要实现应答、超时及重传机制
协议帧类型定义
透传数据的payload格式定义
各字段说明如下：
method
操作的方法。定义如下：
id
帧标识符，用于区分不同的请求。回复帧与请求帧的id必须相同，表示对该帧的回复。
data
数据域，具体格式根据method来确定。
(1) Get方法的data域格式 
(2) Set／Report方法的data域格式 
说明：
（a）属性定义方式：type、attrNameVar；为了方便传输和解析，通过把名词数字化方式定义，给type和attrNameVar分配id值。定义参考下一章节。
（b）len非必须，仅在类型为数组和文本(text)的情况下需要，表示长度。
(3) Service／Event方法的data域格式 
说明：
（a） ID是Service/Event的标识；parameters是Service/Event携带的参数。
（b）示例见后面章节
(4) Ack方法的data域格式 
类型&属性定义
类型定义说明
以下是属性的类型数字化的定义
属性定义说明
自行根据产品功能定义生成。MCU SDK会根据开发者在控制台上定义的功能自动生成相关代码，里面会包括属性的定义。产品功能定义描述参考TSL。
服务&事件定义
云端下发服务或者设备端上报事件是可以携带参数的。
服务
自行根据产品功能定义。MCU SDK会根据开发者在控制台上定义的功能自动生成相关代码，里面会包括服务的定义。产品功能定义描述参考TSL。
事件
自行根据产品功能定义。MCU SDK会根据开发者在控制台上定义的功能自动生成相关代码，里面会包括事件的定义。产品功能定义描述参考TSL。