2016年9月3日 (六) 08:53的最后版本

[编辑] 1 摩羯云 API 编程指南

Author: Huang Rui <vowstar@gmail.com>
Version: 1.0
Date: 2016-01-14

[编辑] 1.1 开始入门

[编辑] 1.1.1 快速尝试

请移步：MJYUN QuickStart

[编辑] 1.1.2 调试设备

进入公众号，点击菜单 -> 添加设备 ->设备调试。此时您就可以调试微信与设备之间的通讯了

[编辑] 1.2 参考模板

更多设备固件设计草图位于：noduino-sdk/sketch 如：

• 用于 WiFi 插座的固件： noduino-sdk/sketch/open-plug
• 用于彩色调光 LED 灯泡的固件： noduino-sdk/sketch/open-bulb
• 用于小 K mini 的固件： noduino-sdk/sketch/plug-min
• 用于 ikair 家庭环境监测的固件：noduino-sdk/sketch/ikair

[编辑] 1.3 接口概述

[编辑] 1.3.1 1. 数据类型

[编辑] 1.3.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.3.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.3.2 2. 回调类型

[编辑] 1.3.2.1 mjyun_callback

硬件与摩羯云发生连接，断开，发布后调用此类型的回调函数。

typedef void (*mjyun_callback)();

[编辑] 1.3.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.3.2.3 mjyun_state_callback

硬件的状态发生改变后，调用此类型的回调函数。

typedef void (*mjyun_state_callback)(mjyun_state_t state);

[编辑] 1.3.3 3. 接口函数

[编辑] 1.3.3.1 mjyun_run

启动摩羯云智能硬件服务

int mjyun_run(const mjyun_config_t* conf);

[编辑] 1.3.3.2 mjyun_ota_config

配置摩羯云OTA升级功能

int mjyun_ota_config(const mjyun_ota_config_t* conf);

[编辑] 1.3.3.3 mjyun_onconnected

注册摩羯云连接成功回调函数

void mjyun_onconnected(mjyun_callback connectedCb);

[编辑] 1.3.3.4 mjyun_ondisconnected

注册摩羯云断开回调函数

void mjyun_ondisconnected(mjyun_callback disconnectedCb);

[编辑] 1.3.3.5 mjyun_ondata

注册摩羯云收到数据回调函数

void mjyun_ondata(mjyun_data_callback dataCb);

[编辑] 1.3.3.6 mjyun_onpublished

注册向摩羯云发布消息结束时触发的回调函数

void mjyun_onpublished(mjyun_callback sendCb);

[编辑] 1.3.3.7 mjyun_publish

向摩羯云（APP或微信页面）发布消息

该消息不会一直保持在服务器上，如果主题(Topic)没有APP订阅，该消息会被丢弃。

BOOL mjyun_publish(const char* event_name, const char* event_data);

[编辑] 1.3.3.8 mjyun_publishstatus

向摩羯云（APP或微信页面）发布设备状态消息

该状态消息会一直保持在服务器上，即使主题没有被任何APP订阅。一旦APP连接到服务器并订阅该主题，将会收到最新的状态消息。

BOOL mjyun_publishstatus(const char* status_data);

[编辑] 1.3.3.9 mjyun_statechanged

注册摩羯云智能硬件状态发生改变的回调函数

void mjyun_statechanged(mjyun_state_callback stateChangedCb);

[编辑] 1.3.3.10 mjyun_state

立即获得摩羯云当前的状态

mjyun_state_t mjyun_state();

[编辑] 1.3.3.11 mjyun_getdevicepasswd

获得设备密码

该API不常用。

uint8_t* mjyun_getdevicepasswd();

[编辑] 1.3.3.12 mjyun_getdeviceid

获得设备ID

uint8_t* mjyun_getdeviceid();

[编辑] 1.3.3.13 mjyun_systemrecovery

系统恢复，抹掉所有摩羯云相关数据

该API一般对应物理按键。

慎用该API，您有可能永久丢失设备ID和密码。

void mjyun_systemrecovery();

[编辑] 1.3.3.14 mjyun_forceentersmartlinkmode

强制进入配网模式

该API一般对应物理按键。

void mjyun_forceentersmartlinkmode(); 

[编辑] 1.3.3.15 mjyun_setssidprefix

设置物理硬件作为AP时的SSID前缀

void mjyun_setssidprefix(const char* sPrefix); 

[编辑] 1.3.3.16 mjyun_check_update

检查固件更新

仅检查更新，不会强制更新固件。是否更新固件由摩羯云进行决策。

void mjyun_check_update();