MJYUN User Guide
小 (Add describe of device debug in document.) |
|||
第250行: | 第250行: | ||
* 设置摩羯云服务器发送给app的设备上线(online)的附加数据 [该数据缺省为设备id] [选填] | * 设置摩羯云服务器发送给app的设备上线(online)的附加数据 [该数据缺省为设备id] [选填] | ||
* 设置摩羯云服务器发送给app的设备离线消息(offline)的附加数据 [该数据缺省为设备id] [选填] | * 设置摩羯云服务器发送给app的设备离线消息(offline)的附加数据 [该数据缺省为设备id] [选填] | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
<br><br> | <br><br> |
2016年7月26日 (二) 17:24的版本
1 摩羯云智能硬件编程指南
Author: Huang Rui <vowstar@gmail.com> Version: 1.0 Date: 2016-01-14
1.1 开始入门
1.1.1 1. 获取Noduino开发环境
安装Git版本控制系统,并获取 https://github.com/icamgo/noduino-sdk[Noduino SDK].
$ git clone --recursive git://github.com/icamgo/noduino-sdk.git
1.1.2 2. 初始化Noduino开发环境
进入./noduino-sdk/toolchain目录,运行gen.py初始化Noduino开发环境。
$ python gen.py
该过程可能需要网络连接,请耐心等待。
1.1.3 3. 编写代码
进入 ./noduino-sdk/sketch/mjyun,打开user_main.c
$ vim user_main.c
编辑mjyun_conf,填入你在云端后台管理系统设定的微信原始ID与产品编码(产品子ID)。
/* 插座 - Plug */ const mjyun_config_t mjyun_conf = { { "gh_51111441aa63", /* 产品id [必填]*/ "3707", /*产品子id(一般用于微信设备) [选填]*/ "Hi, I'm coming!!!", /*设备上线时,给app发送online消息中的附加数据,[选填]*/ "I will come back!!!" /*设备掉线时,给app发送offline消中的附加数据,[选填]*/ }; /* 灯 - Bulb */ const mjyun_config_t mjyun_conf = { { "gh_51111441aa63", /* 产品id [必填]*/ "3708", /*产品子id(一般用于微信设备) [选填]*/ "Hi, I'm coming!!!", /*设备上线时,给app发送online消息中的附加数据,[选填]*/ "I will come back!!!" /*设备掉线时,给app发送offline消中的附加数据,[选填]*/ };
微信中的产品编码等价于摩羯云管理系统中的产品子ID.微信原始ID与摩羯云后台中的产品ID设置需要一致,且代码中必须正确配置。
1.1.4 4. 将硬件通过USB线缆连接至计算机
将摩羯云开发板(Noduino XXX 或 Nemu XXX)通过USB接口连接至计算机。连接硬件之前,请先下载并安装驱动程序。
- 请确认您的计算机安装了FT232/FTX232驱动或者CP2102/CP2104驱动程序。**必须使用高质量的USB线材(最好带屏蔽磁环),否则有可能产生通信错误。**
- FT232驱动下载:
- CP2102驱动下载:
1.1.5 5. 检查您的计算机上是否出现新的串口设备。
- Linux 检查
$ ls /dev/ttyUSB*
- MAC OS 检查
#ft232x ls /dev/cu.usbserial-* #cp210x ls /dev/cu.SLAB_USBtoUART ls /dev/tty.SLAB_USBtoUART ls /dev/cu* ls /dev/tty*
- Windows 检查
- 查看设备管理器
- 在PowerShell中执行以下命令
[System.IO.Ports.SerialPort]::getportnames()
1.1.6 6. 编译并烧写。
$ make clean && make flash
- 如果反复烧写失败,请**按住Flash按键不放,并尝试按一下RESET按键**。
- 烧写过程会缩短Flash的寿命,并破坏Flash上的数据,请先备份Flash上的资料。
1.1.7 7. 使用微信扫描二维码
使用微信扫描二维码后,进入绑定设备与配置Wi-Fi网络的流程。目前提供插座与球泡灯的二维码。
[IMPORTANT]
请确认您在程序中设置了正确的微信原始ID产品编码,否则无法正确发现设备。
根据微信提示,配置和绑定设备。此时会出现摩羯云公众号,选择关注。
- 如果您已经关注了摩羯云公众号,则会跳过关注页面。
1.1.8 8. 开始调试设备
进入摩羯云公众号,点击菜单 -> 探索->设备调试。此时您就可以通过微信与设备之间进行通讯了!
1.2 设备调试
1.2.1 准备工作
你需要一个干净但不算整洁的工作台,一个Noduino-Falcon开发板,Micro USB线。如果你还想自己动手做一些小东西,您还需要购买万用表(推荐用Fluke),电烙铁(936台式烙铁是一个不错的选择),无铅焊锡丝,BGA焊油,镊子等。如果条件允许,您还可以购买一些小工具,元器件册等。推荐使用贴片元件,因为它小巧、便宜、可靠。只要你细心一些,没有什么事情能难住你。
1.2.2 开始调试
Linux, MAC OS, Windows环境都可以。
[NOTE]
其中Windows比较特别,你可能需要mingw或者cygwin,这样你可以运行一个UNIX兼容的console.
想要看调试输出吗?你需要先设置波特率:
stty -F /dev/ttyS2 speed 115200 cs8 -cstopb
[IMPORTANT]
请确认这里设置的波特率和您在程序中设置的波特率相同,否则接下来您什么都看不到。
然后就可以看调试输出了:
cat /dev/ttyS2
或者
cat < /dev/ttyS2
[IMPORTANT]
这里设置的串口名称替代为您本地实际的串口名称,Linux有可能是/dev/ttyUSB*,MAC OS有可能是/dev/cu*或者/dev/tty*.Windows的串口在mingw或cygwin下才能看到,可能是/dev/ttyS*.
[TIP]
如果您使用串口和传感器通讯,您可能对16进制输出更感兴趣,使用命令:
od -x < /dev/ttyS2
1.3 入门例程
#define main user_init void mjyun_receive(const char *event_name, const char *event_data) { os_printf("RECEIVED: key:value [%s]:[%s]", event_name, event_data); } /* * 3707 --> 摩羯插座 * 3708 --> 摩羯灯 */ const mjyun_config_t mjyun_conf = { "gh_51111441aa63", /* 产品id [必填] */ "3707", /* 产品子id (一般用于微信设备) [选填]*/ "Hi, I'm coming!!!", /* 设备上线时,给app发送 online 消息中的附加数据,[选填] */ "I will come back!!!" /* 设备掉线时,给app发送 offline 消息中的附加数据,[选填] */ }; void init_yun() { mjyun_ondata(mjyun_receive); mjyun_run(&mjyun_conf); } void main(int argc, char * argv[]) { system_init_done_cb(init_yun); }
[TIP] 更多例程参见:./noduino-sdk/examples
1.4 接口概述
1.4.1 1. 数据类型
1.4.1.1 mjyun_config_t
该数据结构用于配置智能硬件连接摩羯云需要的必要参数。
typedef struct { const char* product_id; // <1> const char* sub_pid; // <2> const char* online_words; // <3> const char* offline_words; // <4> } mjyun_config_t;
- 产品id, 可从摩羯云官网后台管理系统获得 [必填]
- 产品子id(一般用于微信设备) [选填]
- 设置摩羯云服务器发送给app的设备上线(online)的附加数据 [该数据缺省为设备id] [选填]
- 设置摩羯云服务器发送给app的设备离线消息(offline)的附加数据 [该数据缺省为设备id] [选填]
1.4.1.2 mjyun_state_t
该枚举类型包含了智能硬件的若干种常用状态。
typedef enum { WIFI_IDLE, /*Wi-Fi空闲,常出现在设备刚刚启动且没有连接过任何SSID时*/ WIFI_SMARTLINK_START, /*设备进入智能连接状态*/ WIFI_SMARTLINK_LINKING, /*设备正在进行智能连接*/ WIFI_SMARTLINK_FINDING, /*设备正在进行智能连接,正在查找手机所在的信道与发出的特征包*/ WIFI_SMARTLINK_TIMEOUT, /*设备智能连接超时*/ WIFI_SMARTLINK_GETTING, /*设备正在进行智能连接,已经锁定手机信道,正在解码数据包*/ WIFI_SMARTLINK_OK, /*设备智能连接成功*/ WIFI_AP_OK, /*设备在AP模式*/ WIFI_AP_ERROR, /*设备在AP模式并发生了某些错误*/ WIFI_AP_STATION_OK, /*设备在AP-STATION混合模式*/ WIFI_AP_STATION_ERROR, /*设备在AP-STATION混合模式并发生了某些错误*/ WIFI_STATION_OK, /*设备在STATION模式*/ WIFI_STATION_ERROR, /*设备在STATION模式并发生了某些错误*/ MJYUN_CONNECTING, /*正在连接摩羯云*/ MJYUN_CONNECTING_ERROR, /*连接摩羯云失败*/ MJYUN_CONNECTED, /*已连接摩羯云*/ MJYUN_DISCONNECTED, /*与摩羯云的连接断开*/ } mjyun_state_t;
1.4.2 2. 回调类型
1.4.2.1 mjyun_callback
硬件与摩羯云发生连接,断开,发布后调用此类型的回调函数。
typedef void (*mjyun_callback)();
1.4.2.2 mjyun_data_callback
硬件收到来自摩羯云或者APP的数据后,调用此类型的回调函数。
typedef void (*mjyun_data_callback)(const char *event_name, const char *event_data);
[TIP] event_name和event_data可以看作是** (key,value) **.他们有可能是字符串化的JSON对象。
1.4.2.3 mjyun_state_callback
硬件的状态发生改变后,调用此类型的回调函数。
typedef void (*mjyun_state_callback)(mjyun_state_t state);
1.4.3 3. 接口函数
1.4.3.1 mjyun_run
启动摩羯云智能硬件服务
int mjyun_run(const mjyun_config_t* conf);
1.4.3.2 mjyun_ota_config
配置摩羯云OTA升级功能
int mjyun_ota_config(const mjyun_ota_config_t* conf);
1.4.3.3 mjyun_onconnected
注册摩羯云连接成功回调函数
void mjyun_onconnected(mjyun_callback connectedCb);
1.4.3.4 mjyun_ondisconnected
注册摩羯云断开回调函数
void mjyun_ondisconnected(mjyun_callback disconnectedCb);
1.4.3.5 mjyun_ondata
注册摩羯云收到数据回调函数
void mjyun_ondata(mjyun_data_callback dataCb);
1.4.3.6 mjyun_onpublished
注册向摩羯云发布消息结束时触发的回调函数
void mjyun_onpublished(mjyun_callback sendCb);
1.4.3.7 mjyun_publish
向摩羯云(APP或微信页面)发布消息
- 该消息不会一直保持在服务器上,如果主题(Topic)没有APP订阅,该消息会被丢弃。
BOOL mjyun_publish(const char* event_name, const char* event_data);
1.4.3.8 mjyun_publishstatus
向摩羯云(APP或微信页面)发布设备状态消息
- 该状态消息会一直保持在服务器上,即使主题没有被任何APP订阅。一旦APP连接到服务器并订阅该主题,将会收到最新的状态消息。
BOOL mjyun_publishstatus(const char* status_data);
1.4.3.9 mjyun_statechanged
注册摩羯云智能硬件状态发生改变的回调函数
void mjyun_statechanged(mjyun_state_callback stateChangedCb);
1.4.3.10 mjyun_state
立即获得摩羯云当前的状态
mjyun_state_t mjyun_state();
1.4.3.11 mjyun_getdevicepasswd
获得设备密码
- 该API不常用。
uint8_t* mjyun_getdevicepasswd();
1.4.3.12 mjyun_getdeviceid
获得设备ID
uint8_t* mjyun_getdeviceid();
1.4.3.13 mjyun_systemrecovery
系统恢复,抹掉所有摩羯云相关数据
该API一般对应物理按键。
- 慎用该API,您有可能永久丢失设备ID和密码。
void mjyun_systemrecovery();
1.4.3.14 mjyun_forceentersmartlinkmode
强制进入配网模式
- 该API一般对应物理按键。
void mjyun_forceentersmartlinkmode();
1.4.3.15 mjyun_setssidprefix
设置物理硬件作为AP时的SSID前缀
void mjyun_setssidprefix(const char* sPrefix);
1.4.3.16 mjyun_check_update
检查固件更新
- 仅检查更新,不会强制更新固件。是否更新固件由摩羯云进行决策。
void mjyun_check_update();