全部产品
云市场

一键配网

更新时间:2019-03-15 17:20:08

方案说明

一键配网方案中, 手机将WiFi热点的SSID/密码通过特殊编码方法在WiFi的数据或管理帧上进行广播发送

设备可监听WiFi数据帧或管理帧来将SSID/密码进行解码, 然后用获取到的SSID/密码去连接WiFi热点

工作原理如下所示

说明

  • 手机连接到WiFi热点上, 然后在固定的信道上广播发送SSID/密码的编码字节
  • 设备轮询所有的WiFi信道去检测是否有配网通告, 如果检测到则从配网通告中解码出WiFi热点的SSID/密码

注: IoT设备大多数只支持2.4GHz频段, 所以目前的一键配网方案设备端实现只是在2.4GHz的1~13信道上进行配网帧检测

如何配置使用这种配网模式

通过menuconfig选择配网模块并选定一键配网:

  1. make distclean
  2. make menuconfig

使能配网:

选择一键配网:

API使用范例

下面是设备上电后的配网代码示例:

  1. uint8_t bssid[ETH_ALEN] = {0};
  2. char ssid[HAL_MAX_SSID_LEN] = {0};
  3. char passwd[HAL_MAX_PASSWORD_LEN] = {0};
  4. // Users need to get the stord ssid/passwd, to decide whether to start wifi provisioning service
  5. if (INVALID_SSID(ssid) || INVALID_BSSID(bssid) ) {
  6. awss_start();
  7. } else {
  8. HAL_Awss_Connect_Ap(TIMEOUT_MS, ssid, passwd, 0, 0, bssid, 0);
  9. }
  10. // Note:
  11. // 1. Device wouldn't parse awss packet until application calls awss_config_press
  12. // 2. Application can detect butturn press or the others method of user touch
  13. // to call the operation of calling awss_config_press.

上面代码演示了上电后根据设备内是否存储了ssid/password来判断是否需要启动配网. 启动配网后出于安全考虑并不会直接解awss包进行配网, 当真正需要配网时, 需要调用awss_config_press接口使能配网:

  1. extern int awss_config_press();
  2. awss_config_press();

配网过程状态监控如果应用程序需要感知配网过程中的状态变化, 可以注册事件回调函数, 当相关事件发生时, 配网模块会调用回调函数告知具体的事件, 设备商可以在相关事件中操作LED指示灯的亮或灭, 或者通过快闪/慢闪来告知用户状态的变化, 也可以播放声音来告知用户状态

参考示例如下:

  1. // 注册事件回调函数, 注册配网事件回调一定要需在awss_start之前调用
  2. iotx_event_regist_cb(linkkit_event_monitor);
  3. // linkkit_event_monitor是事件回调函数参考事件:
  4. static void linkkit_event_monitor(int event)
  5. {
  6. switch (event) {
  7. case IOTX_AWSS_START: // AWSS start without enbale, just supports device discover
  8. // operate led to indicate user
  9. LOG("IOTX_AWSS_START");
  10. break;
  11. case IOTX_AWSS_ENABLE: // AWSS enable, AWSS doesn't parse awss packet until AWSS is enabled.
  12. LOG("IOTX_AWSS_ENABLE");
  13. // operate led to indicate user
  14. break;
  15. case IOTX_AWSS_LOCK_CHAN: // AWSS lock channel(Got AWSS sync packet)
  16. LOG("IOTX_AWSS_LOCK_CHAN");
  17. // operate led to indicate user
  18. break;
  19. case IOTX_AWSS_PASSWD_ERR: // AWSS decrypt passwd error
  20. LOG("IOTX_AWSS_PASSWD_ERR");
  21. // operate led to indicate user
  22. break;
  23. case IOTX_AWSS_GOT_SSID_PASSWD:
  24. LOG("IOTX_AWSS_GOT_SSID_PASSWD");
  25. // operate led to indicate user
  26. break;
  27. case IOTX_AWSS_CONNECT_ADHA: // AWSS try to connnect adha (device
  28. // discover, router solution)
  29. LOG("IOTX_AWSS_CONNECT_ADHA");
  30. // operate led to indicate user
  31. break;
  32. case IOTX_AWSS_CONNECT_ADHA_FAIL: // AWSS fails to connect adha
  33. LOG("IOTX_AWSS_CONNECT_ADHA_FAIL");
  34. // operate led to indicate user
  35. break;
  36. case IOTX_AWSS_CONNECT_AHA: // AWSS try to connect aha (AP solution)
  37. LOG("IOTX_AWSS_CONNECT_AHA");
  38. // operate led to indicate user
  39. break;
  40. case IOTX_AWSS_CONNECT_AHA_FAIL: // AWSS fails to connect aha
  41. LOG("IOTX_AWSS_CONNECT_AHA_FAIL");
  42. // operate led to indicate user
  43. break;
  44. case IOTX_AWSS_SETUP_NOTIFY: // AWSS sends out device setup information
  45. // (AP and router solution)
  46. LOG("IOTX_AWSS_SETUP_NOTIFY");
  47. // operate led to indicate user
  48. break;
  49. case IOTX_AWSS_CONNECT_ROUTER: // AWSS try to connect destination router
  50. LOG("IOTX_AWSS_CONNECT_ROUTER");
  51. // operate led to indicate user
  52. break;
  53. case IOTX_AWSS_CONNECT_ROUTER_FAIL: // AWSS fails to connect destination
  54. // router.
  55. LOG("IOTX_AWSS_CONNECT_ROUTER_FAIL");
  56. // operate led to indicate user
  57. break;
  58. case IOTX_AWSS_GOT_IP: // AWSS connects destination successfully and got
  59. // ip address
  60. LOG("IOTX_AWSS_GOT_IP");
  61. // operate led to indicate user
  62. break;
  63. case IOTX_AWSS_SUC_NOTIFY: // AWSS sends out success notify (AWSS
  64. // sucess)
  65. LOG("IOTX_AWSS_SUC_NOTIFY");
  66. // operate led to indicate user
  67. break;
  68. case IOTX_AWSS_BIND_NOTIFY: // AWSS sends out bind notify information to
  69. // support bind between user and device
  70. LOG("IOTX_AWSS_BIND_NOTIFY");
  71. // operate led to indicate user
  72. break;
  73. case IOTX_AWSS_ENABLE_TIMEOUT: // AWSS enable timeout
  74. // user needs to enable awss again to support get ssid & passwd of router
  75. LOG("IOTX_AWSS_ENALBE_TIMEOUT");
  76. // operate led to indicate user
  77. break;
  78. case IOTX_CONN_CLOUD: // Device try to connect cloud
  79. LOG("IOTX_CONN_CLOUD");
  80. // operate led to indicate user
  81. break;
  82. case IOTX_CONN_CLOUD_FAIL: // Device fails to connect cloud, refer to
  83. // net_sockets.h for error code
  84. LOG("IOTX_CONN_CLOUD_FAIL");
  85. // operate led to indicate user
  86. break;
  87. case IOTX_CONN_CLOUD_SUC: // Device connects cloud successfully
  88. LOG("IOTX_CONN_CLOUD_SUC");
  89. // operate led to indicate user
  90. break;
  91. case IOTX_RESET: // Linkkit reset success (just got reset response from
  92. // cloud without any other operation)
  93. LOG("IOTX_RESET");
  94. // operate led to indicate user
  95. break;
  96. default:
  97. break;
  98. }
  99. }

API接口说明

序号 函数名 说明
1 awss_start 开启配网服务(设备热点配网除外)
2 awss_config_press 使能配网, 开始解包
3 awss_stop 关闭配网服务(设备热点配网除外)

应用场景

awss_start

调用该API用于启动配网服务. 启动配网服务的场景包括:

设备首次上电, 设备上不存在热点SSID/密码.用户希望设备重新进行配网调用该配网服务后, 设备进入配网发现状态, 用于让网络中的其它设备发现自己的存在. 但是在这个状态中, 设备并不会接受来自手机或者其它设备推送的SSID/密码

设备上电时若已有SSID/密码, 直接调用HAL_Awss_Connect_Ap()去连接WiFi热点

awss_config_press

为了安全考虑, 设备上通常具备一个配网按键, 当该按键被按下时设备才会接受来自手机或者其它设备推送的SSID/密码, 设备商需要实现代码来感知配网按键被按下, 并调用本函数让设备接收手机或者其它设备推送的SSID/密码信息

该函数被调用之后, 只有在HAL_Awss_Get_Timeout_Interval_Ms()指定的时间间隔内会接收手机或者设备推送的SSID/密码

说明:

  • 若设备无法设计一个专门的配网按键, 可以通过长按(比如3秒)设备上的某个按键来表示允许接收WiFi热点信息.
  • 若设备希望设备上电就可以接受手机或者其它设备推送的WiFi热点信息, 那么可以调用awss_start()之后直接调用awss_config_press()

awss_stop

调用该API用于停止当前配网. 停止服务的场景包括:

  • 当前不需要配网, 希望停止配网服务
  • 希望通过其他途径配网, 切换配网(如设备热点配网, 第三方配网)

需要对接的HAL接口

除wifi配网概述里面列出的通用HAL API需要对接外, 还需要对接以下HAL:

序号 函数名 说明
1 HAL_Awss_Get_Encrypt_Type 获取smartconfig/设备热点配网服务的安全等级

说明:

配网的安全等级必须小于等于Link kit连云的安全等级, 比如Link kit连云设置为一型一密, 此处设置为4会出现配网失败的情况.