2C-ESP8266_Non_OS_SDK_API_Reference__CN.pages

Transcription

1 ESP8266 Non-OS SDK API 参考 版本 3.0 乐鑫信息科技 版权所有

2 关于本 手册 本 文档提供 ESP8266_NONOS_SDK 的 API 说明 发布说明 日期版本发布说明 V1.5.2 更更新章节 3.2 A.5 和 V V V V2.0.1 新增章节 和 更更新章节 和 新增章节 和 更更新章节 3.7 更更新章节 和 新增章节 和 将章节 中的 wifi_station_get_hostname 改为 wifi_station_set_hostname V2.0.2 更更新第 2 章 V2.1.0 新增章节 ,3.3.50,4.3.6 和 V2.1.1 更更新第 2 章 V2.1.2 更更新章节 V2.2 更更新章节 6.2.1,6.2.3,6.2.4, 新增章节 3.4.8,3.4.9,3.5.74, V2.2.1 更更新章节 2.4,3.5.54, V3.0 新增章节 ,3.3.51,3.3.52,3.5.76,3.5.77,3.5.78, , 附录 A.6 更更新章节 2.5 删除 system_phy_freq_trace_enable

3 文档变更更通知 用户可通过乐鑫官 网订阅 页 面 订阅技术 文档变更更的电 子邮件通知 证书下载 用户可通过乐鑫官 网证书下载 页 面 下载产品证书

4 目录 1. 前 言 Non-OS SDK Non-OS SDK 简介 代码结构 定时器器 (timer) 和中断 系统性能 系统存储 应 用程序接 口 (API) 软件定时器器 os_timer_arm os_timer_disarm os_timer_setfn system_timer_reinit os_timer_arm_us 硬件中断定时器器 hw_timer_init hw_timer_arm hw_timer_set_func 硬件定时器器示例例 系统接 口 system_get_sdk_version system_restore system_restart system_init_done_cb system_get_chip_id system_get_vdd system_adc_read system_adc_read_fast system_deep_sleep... 14

5 system_deep_sleep_set_option system_phy_set_rfoption system_phy_set_powerup_option system_phy_set_max_tpw system_phy_set_tpw_via_vdd system_set_os_print system_print_meminfo system_get_free_heap_size system_os_task system_os_post system_get_time system_get_rtc_time system_rtc_clock_cali_proc system_rtc_mem_write system_rtc_mem_read system_uart_swap system_uart_de_swap system_get_boot_version system_get_userbin_addr system_get_boot_mode system_restart_enhance system_update_cpu_req system_get_cpu_freq system_get_flash_size_map system_get_rst_info system_soft_wdt_stop system_soft_wdt_restart system_soft_wdt_feed system_show_malloc os_memset os_memcpy os_strlen os_printf os_bzero... 25

6 os_delay_us os_install_putc os_random os_get_random user_rf_cal_sector_set system_deep_sleep_instant system_partition_table_regist system_partition_get_ota_partition_size system_partition_get_item SPI Flash 接 口 spi_flash_get_id spi_flash_erase_sector spi_flash_write spi_flash_read system_param_save_with_protect system_param_load spi_flash_set_read_func spi_flash_erase_protect_enable spi_flash_erase_protect_disable Wi-Fi 接 口 wifi_get_opmode wifi_get_opmode_default wifi_set_opmode wifi_set_opmode_current wifi_station_get_config wifi_station_get_config_default wifi_station_set_config wifi_station_set_config_current wifi_station_set_cert_key wifi_station_clear_cert_key wifi_station_set_username wifi_station_clear_username wifi_station_connect wifi_station_disconnect... 38

7 wifi_station_get_connect_status wifi_station_scan scan_done_cb_t wifi_station_ap_number_set wifi_station_get_ap_info wifi_station_ap_change wifi_station_get_current_ap_id wifi_station_get_auto_connect wifi_station_set_auto_connect wifi_station_dhcpc_start wifi_station_dhcpc_stop wifi_station_dhcpc_status wifi_station_dhcpc_set_maxtry wifi_station_set_reconnect_policy wifi_station_get_rssi wifi_station_set_hostname wifi_station_get_hostname wifi_softap_get_config wifi_softap_get_config_default wifi_softap_set_config wifi_softap_set_config_current wifi_softap_get_station_num wifi_softap_get_station_info wifi_softap_free_station_info wifi_softap_dhcps_start wifi_softap_dhcps_stop wifi_softap_set_dhcps_lease wifi_softap_get_dhcps_lease wifi_softap_set_dhcps_lease_time wifi_softap_get_dhcps_lease_time wifi_softap_reset_dhcps_lease_time wifi_softap_dhcps_status wifi_softap_set_dhcps_offer_option wifi_set_phy_mode... 48

8 wifi_get_phy_mode wifi_get_ip_info wifi_set_ip_info wifi_set_macaddr wifi_get_macaddr wifi_set_sleep_type wifi_get_sleep_type wifi_status_led_install wifi_status_led_uninstall wifi_set_broadcast_if wifi_get_broadcast_if wifi_set_event_handler_cb wifi_wps_enable wifi_wps_disable wifi_wps_start wifi_set_wps_cb wifi_register_send_pkt_freedom_cb wifi_unregister_send_pkt_freedom_cb wifi_send_pkt_freedom wifi_rfid_locp_recv_open wifi_rfid_locp_recv_close wifi_register_rfid_locp_recv_cb wifi_unregister_rfid_locp_recv_cb wifi_enable_gpio_wakeup wifi_disable_gpio_wakeup wifi_set_country wifi_get_country wifi_set_sleep_level wifi_get_sleep_level wifi_set_listen_interval wifi_get_listen_interval Rate Control 接 口 wifi_set_user_fixed_rate wifi_get_user_fixed_rate... 61

9 wifi_set_user_sup_rate wifi_set_user_rate_limit wifi_set_user_limit_rate_mask wifi_get_user_limit_rate_mask 强制休眠接 口 wifi_fpm_open wifi_fpm_close wifi_fpm_do_wakeup wifi_fpm_set_wakeup_cb wifi_fpm_do_sleep wifi_fpm_set_sleep_type wifi_fpm_get_sleep_type wifi_fpm_auto_sleep_set_in_null_mode 示例例代码 ESP-NOW 接 口 结构体 esp_now_init esp_now_deinit esp_now_register_recv_cb esp_now_unregister_recv_cb esp_now_register_send_cb esp_now_unregister_send_cb esp_now_send esp_now_add_peer esp_now_del_peer esp_now_set_self_role esp_now_get_self_role esp_now_set_peer_role esp_now_get_peer_role esp_now_set_peer_key esp_now_get_peer_key esp_now_set_peer_channel esp_now_get_peer_channel esp_now_is_peer_exist... 75

10 esp_now_fetch_peer esp_now_get_cnt_info esp_now_set_kok Simple-Pair 接 口 结构体 register_simple_pair_status_cb unregister_simple_pair_status_cb simple_pair_init simple_pair_deinit simple_pair_state_reset simple_pair_ap_enter_announce_mode simple_pair_sta_enter_scan_mode simple_pair_sta_start_negotiate simple_pair_ap_start_negotiate simple_pair_ap_refuse_negotiate simple_pair_set_peer_ref simple_pair_get_peer_ref 云端升级 (FOTA) 接 口 system_upgrade_userbin_check system_upgrade_flag_set system_upgrade_flag_check system_upgrade_start system_upgrade_reboot Sniffer 相关接 口 wifi_promiscuous_enable wifi_promiscuous_set_mac wifi_set_promiscuous_rx_cb wifi_get_channel wifi_set_channel SmartConfig 接 口 smartconfig_start smartconfig_stop smartconfig_set_type airkiss_version... 87

11 airkiss_lan_recv airkiss_lan_pack SNTP 接 口 sntp_setserver sntp_getserver sntp_setservername sntp_getservername sntp_init sntp_stop sntp_get_current_timestamp sntp_get_real_time sntp_set_timezone sntp_get_timezone SNTP 示例例 WPA2-Enterprise 接 口 wifi_station_set_wpa2_enterprise_auth wifi_station_set_enterprise_cert_key wifi_station_clear_enterprise_cert_key wifi_station_set_enterprise_ca_cert wifi_station_clear_enterprise_ca_cert wifi_station_set_enterprise_username wifi_station_clear_enterprise_username wifi_station_set_enterprise_password wifi_station_clear_enterprise_password wifi_station_set_enterprise_new_password wifi_station_clear_enterprise_new_password wifi_station_set_enterprise_disable_time_check wifi_station_get_enterprise_disable_time_check wpa2_enterprise_set_user_get_time 示例例流程 TCP/UDP 接 口 通 用接 口 espconn_delete... 97

12 espconn_gethostbyname espconn_port espconn_regist_sentcb espconn_regist_recvcb espconn_sent_callback espconn_recv_callback espconn_get_connection_info espconn_send espconn_sent TCP 接 口 espconn_accept espconn_regist_time espconn_connect espconn_regist_connectcb espconn_connect_callback espconn_set_opt espconn_clear_opt espconn_set_keepalive espconn_get_keepalive espconn_reconnect_callback espconn_regist_reconcb espconn_disconnect espconn_regist_disconcb espconn_abort espconn_regist_write_finish espconn_tcp_get_max_con espconn_tcp_set_max_con espconn_tcp_get_max_con_allow espconn_tcp_set_max_con_allow espconn_recv_hold espconn_recv_unhold espconn_secure_accept espconn_secure_delete espconn_secure_set_size

13 espconn_secure_get_size espconn_secure_connect espconn_secure_send espconn_secure_sent espconn_secure_disconnect espconn_secure_ca_enable espconn_secure_ca_disable espconn_secure_cert_req_enable espconn_secure_cert_req_disable espconn_secure_set_default_certificate espconn_secure_set_default_private_key UDP 接 口 espconn_create espconn_sendto espconn_igmp_join espconn_igmp_leave espconn_dns_setserver espconn_dns_getserver mdns 接 口 espconn_mdns_init espconn_mdns_close espconn_mdns_server_register espconn_mdns_server_unregister espconn_mdns_get_servername espconn_mdns_set_servername espconn_mdns_set_hostname espconn_mdns_get_hostname espconn_mdns_disable espconn_mdns_enable mdns 示例例 应 用相关接 口 AT 接 口 at_response_ok

14 at_response_error at_cmd_array_regist at_get_next_int_dec at_data_str_copy at_init at_port_print at_set_custom_info at_enter_special_state at_leave_special_state at_get_version at_register_uart_rx_intr at_response at_register_response_func at_fake_uart_enable at_fake_uart_rx at_set_escape_character JSON 接 口 jsonparse_setup jsonparse_next jsonparse_copy_value jsonparse_get_value_as_int jsonparse_get_value_as_long jsonparse_get_len jsonparse_get_value_as_type jsonparse_strcmp_value jsontree_set_up jsontree_reset jsontree_path_name jsontree_write_int jsontree_write_int_array jsontree_write_string jsontree_print_next jsontree_find_next 结构体和宏定义

15 6.1. 定时器器 Wi-Fi Station SoftAP Scan Wi-Fi Event 结构体 SmartConfig 结构体 JSON 相关结构体 JSON 结构体 JSON 宏定义 espconn 回调函数 espconn 中断相关宏定义 外设驱动接 口 GPIO 接 口 PIN 相关宏定义 gpio_output_set GPIO 输 入输出相关宏 GPIO 中断 gpio_pin_intr_state_set GPIO 中断处理理函数 UART 接 口 uart_init uart0_tx_buffer uart0_rx_intr_handler uart_div_modify I2C Master 接 口 i2c_master_gpio_init i2c_master_init

16 i2c_master_start i2c_master_stop i2c_master_send_ack i2c_master_send_nack i2c_master_checkack i2c_master_readbyte i2c_master_writebyte PWM 接 口 pwm_init pwm_start pwm_set_duty pwm_get_duty pwm_set_period pwm_get_period get_pwm_version SDIO 接 口 sdio_slave_init sdio_load_data sdio_register_recv_cb A. 附录 A.1. ESPCONN 编程 A.1.1. TCP Client 模式 A.1.2. TCP Server 模式 A.1.3. espconn Callback A.2. RTC API 使 用示例例 A.3. Sniffer 说明 A.4. ESP8266 SoftAP 和 Station 信道定义 A.5. ESP8266 启动信息说明 A.6. ESP8266 信令测试使 用说明

17 ! 1. 前 言 1. 前 言 ESP8266EX 由乐鑫公司开发, 提供了了 一套 高度集成的 Wi-Fi SoC 解决 方案, 其低功耗 紧凑设计和 高稳定性可以满 足 用户的需求 ESP8266EX 拥有完整的且 自成体系的 Wi-Fi 网络, 既能够独 立应 用, 也可以作为从机搭载于其他主机 MCU 运 行行 当 ESP8266EX 独 立应 用时, 能够直接从外接 Flash 中启动 内置的 高速缓冲存储器器有利利于提 高系统性能, 并且优化存储系统 此外 ESP8266EX 只需通过 SPI/SDIO 接 口或 I2C/UART 口即可作为 Wi-Fi 适配器器, 应 用到基于任何微控制器器的设计中 ESP8266EX 集成了了天线开关 射频 balun 功耗放 大器器 低噪放 大器器 过滤器器和电源管理理模块 这样紧凑的设计仅需极少的外部电路路并且将 PCB 的尺 寸降到最 小 ESP8266EX 还集成了了增强版的 Tensilica s L106 钻 石系列列 32-bit 内核处理理器器, 带 片上 SRAM ESP8266EX 可以通过 GPIO 外接传感器器和其他设备 软件开发包 (SDK) 提供了了 一些应 用的示例例代码 乐鑫智能互联平台 (ESCP-Espressif Systems Smart Connectivity Platform) 表现出来的领先特征有 : 睡眠 / 唤醒模式之间的快速切换以实现节能 配合低功耗操作的 自适应射频偏置 前端信号的处理理 故障排除和射频共存机制可消除蜂窝 / 蓝 牙 /DDR/LVDS/LCD 干扰 基于 ESP8266EX 物联 网平台的 SDK 为 用户提供了了 一个简单 快速 高效开发物联 网产品的软件平台 本 文旨在介绍该 SDK 的基本框架, 以及相关的 API 接 口 主要的阅读对象为需要在 ESP8266 物联 网平台进 行行软件开发的嵌 入式软件开发 人员 Espressif 1! /! 153

18 ! 2. Non-OS SDK 2. Non-OS SDK 2.1. Non-OS SDK 简介 Non-OS SDK 为 用户提供了了 一套应 用程序编程接 口 (API), 能够实现 ESP8266 的核 心改, 例例如数据接收 / 发送 TCP/IP 硬件接 口, 以及基本的系统管理理等 用户不不必关 心底层 网络, 如 Wi-Fi TCP/IP 等的具体实现, 只需要专注于物联 网上层应 用的开发, 利利 用相应接 口实现各种即可 ESP8266 物联 网平台的所有 网络均在库中实现, 对 用户不不透明 用户应 用的初始化可以在 user_main.c 中实现 void user_init(void) 是上层程序的 入 口函数, 给 用户提供 一个初始化接 口, 用户可在该函数内增加硬件初始化 网络设置 定时器器初始化等 对于 ESP8266_NONOS_SDK_v3.0.0 及之后版本, 请在 user_main.c 增加函数 void ICACHE_FLASH_ATTR user_pre_init(void), 并且在 user_pre_init 中注册 自 己的 partition table 对于 ESP8266_NONOS_SDK_v1.5.2 至 ESP8266_NONOS_SDK_v2.2.1 之间的版本, 请在 user_main.c 增加函数 void user_rf_pre_init(void) 和 uint32 user_rf_cal_sector_set(void), 可参考 IOT_Demo 的 user_main.c 用户可在 user_rf_pre_init 中配置 RF 初始化,RF 设置接 口为 system_phy_set_rfoption, 或者在 Deep-sleep 前调 用 system_deep_sleep_set_option 如果设置为 RF 不不打开, 则 ESP8266 Station 及 SoftAP 均法使 用, 请勿调 用 Wi-Fi 相关接 口及 网络 RF 关闭时,Wi-Fi 射频和 网络堆栈管理理 API 均法使 用 对于 ESP8266_NONOS_SDK_v2.1.0 及之后版本, 用户如果并未使 用 DIO-To-QIO flash, 可以在 user_main.c 中增加空函数 void user_spi_flash_dio_to_qio_pre_init(void) 来优化 iram 空间 SDK 中提供了了对 JSON 包的处理理 API, 用户也可以采 用 自定义数据包格式, 自 行行对数据进 行行处理理 2.2. 代码结构 Non-OS SDK 适 用于 用户需要完全控制代码执 行行顺序的应 用程序 由于没有操作系统, non-os SDK 不不 支持任务调度, 也不不 支持基于优先级的抢占 Non-OS SDK 最适合 用于事件驱动的应 用程序 由于没有操作系统,non-OS SDK 没有单个任务堆栈 大 小的限制或者执 行行时隙要求 Espressif 2! /! 153

19 ! 2. Non-OS SDK 而 RTOS SDK 可 用于基于任务的模块化编程 要了了解有关 RTOS SDK 的更更多信息, 请参阅 ESP8266 SDK 入 门指南 Non-OS SDK 中的代码结构具有以下特征 : Non-OS SDK 不不像基于 RTOS 的应 用程序 支持任务调度 Non-OS SDK 使 用四种类型的函数 : - 应 用函数 - 回调函数 - 用户任务 - 中断服务程序 (Interrupt Service Routines, ISR) 应 用函数类似于嵌 入式 C 编程中的常 用 C 函数 这些函数必须由另 一个函数调 用 应 用函数在定义时建议添加 ICACHE_FLASH_ATTR 宏, 相应程序将存放在 flash 中, 被调 用时才加载到 cache 运 行行 而如果添加了了 IRAM_ATTR 宏的函数, 则会在上电启动时就加载到 iram 中 回调函数是指不不直接从 用户程序调 用的函数, 而是当某系统事件发 生时, 相应的回调函数由 non-os SDK 内核调 用执 行行 这使得开发者能够在不不使 用 RTOS 或者轮询事件的情况下响应实时事件 要编写回调函数, 用户 首先需要使 用相应的 register_cb API 注册回调函数 回调函数的示例例包括定时器器回调函数和 网络事件回调函数 中断服务程序 (ISR) 是 一种特殊类型的回调函数 发 生硬件中断时会调 用这些函数 当使能中断时, 必须注册相应的中断处理理函数 请注意,ISR 必须添加 IRAM_ATTR 用户任务可以分为三个优先级 :0 1 2 任务优先级为 2 > 1 > 0 即 Non-OS SDK 最多只 支持 3 个 用户任务, 优先级分别为 用户任务 一般 用于函数不不能直接被调 用的情况下 要创建 用户任务, 请参阅本 文档中的 system_os_task() 的 API 描述 例例如,espconn_disconnect() API 不不能直接在 espconn 的回调函数中调 用, 因此建议开发者可以在 espconn 回调中创建 用户任务来执 行行 espconn_disconnect 如前所述,non-OS SDK 不不 支持抢占任务或进程切换 因此开发者需要 自 行行保证程序的正确执 行行, 用户代码不不能 长期占 用 CPU 否则会导致看 门狗复位,ESP8266 重启 如果某些特殊情况下, 用户线程必须执 行行较 长时间 ( 比如 大于 500 ms), 建议经常调 用 system_soft_wdt_feed() API 来喂软件看 门狗, 而不不建议禁 用软件看 门狗 Espressif 3! /! 153

20 ! 2. Non-OS SDK 请注意,esp_init_data.bin 和 blank.bin 文件 至少需要烧录 一次, 以 用于正确的初 2.3. 定时器器 (timer) 和中断 2.4. 系统性能 2.5. 系统存储 始化系统 对于 ESP8266_NONOS_SDK_v2.2.1 及之前的版本, 应 用程序必须在 user_rf_cal_sector_set 中设置 RF 校准扇区 对于需要进 行行轮询的应 用, 建议使 用系统定时器器定期检查事件 - 如果使 用循环 (while 或 for), 不不仅效率低下, 而且阻塞 CPU, 不不建议使 用 - 如果需要在定时器器回调中执 行行 os_delay_us 或 while 或 for, 请勿占 用 CPU 超过 15 ms 请勿频繁调 用定时器器, 建议频率不不 高于每 5 ms 一次 ( 微秒计时器器则为 100 μs) 有关 定时器器使 用的详细信息, 请参阅 os_timer_arm() 和相关的 API 说明 微秒定时器器不不是很精确, 请在回调中考虑 500 μs 的抖动 如需实现 高精度的定时, 可 以参考驱动程序 (driver_lib) 使 用硬件定时器器 请注意,PWM API 不不能与硬件定时器器同 时使 用 请勿 长时间关闭中断 ISR 执 行行时间也应当尽可能短 ( 即微秒级 ) ESP8266 通常的运 行行速率为 80 MHz, 在 高性能应 用中也可以配置为 160 MHz 请注 意, 外设不不受 CPU 频率设置的影响, 因为它们使 用了了不不同的时钟源 设置更更 高的时钟频率或者禁 用睡眠模式, 会导致更更 大的功耗, 但能获得更更好的性能 应 用程序应考虑两者之间的平衡 添加了了 ICACHE_FLASH_ATTR 的代码通常 比使 用 IRAM_ATTR 标记的代码执 行行得慢 然 而, 像 大多数嵌 入式平台 一样,ESP8266 的 iram 空间有限, 因此建议 一般代码添加 ICACHE_FLASH_ATTR, 仅对执 行行效率要求 高的代码添加 IRAM_ATTR 宏 Flash 模式和频率直接影响代码执 行行速度 将 flash 设置为更更 高的频率和 QIO 模式会产 生更更好的性能, 但会导致更更 大的功耗 ESP8266 支持 高达 128 Mbits 的外部 QSPI flash, 用于存储代码和数据 也可以使 用辅 助存储芯 片来存储 用户数据 ESP8266 没有存储 用户代码或数据的 非易易失性存储 ESP8285 是 一款在 ESP8266 的 基础上集成了了 flash 的芯 片 更更多详细信息请参考 ESP8285 技术规格书 Espressif 4! /! 153

21 ! 2. Non-OS SDK ESP8266 带有 160 KB 的 RAM, 其中 64 KB 为 iram,96 KB 为 dram iram 进 一步分成两块 :32 KB iram 块运 行行标有 IRAM_ATTR 的代码, 另 一个 32 KB 块 用作 cache, 运 行行标有 ICACHE_FLASH_ATTR 的代码 从 ESP8266_NonOS_SDK_V3.0 开始, 增加了了 支持使 用 iram 作为内存的, 能够多提供约 17 KB 的内存, 对性能可能有 一定的影响, 请根据实际应 用需求设置, 并建议做详细测试进 行行确认 使 用 方法如下 : - 在应 用中定义 user_iram_memory_is_enabled 函数并设置值为 1 示例例: #define CONFIG_ENABLE_IRAM_MEMORY 1 #ifdef CONFIG_ENABLE_IRAM_MEMORY uint32 user_iram_memory_is_enabled(void) { return CONFIG_ENABLE_IRAM_MEMORY; } #endif - 如上设置后, 默认使 用 IRAM 作为内存,os_malloc os_zalloc 和 os_calloc 优先从 iram 分配,iRAM 用尽后会继续使 用 dram 分配 ; - 或者直接调 用 os_malloc_iram os_zalloc_iram os_calloc_iram 指定从 iram 分配内存,iRAM 用尽后会继续使 用 dram 分配 ; 直接调 用 os_malloc_dram os_zalloc_dram os_calloc_dram 指定从 dram 分配内存 ; - 如需与旧版本兼容, 可使能宏 MEM_DEFAULT_USE_DRAM,os_malloc os_zalloc 和 os_calloc 将从 dram 分配, 而 os_malloc_iram os_zalloc_iram os_calloc_iram 可以指定从 iram 分配,iRAM 用尽后会继续使 用 dram 分配 例例如, 在 makefile 中添加 : CONFIGURATION_DEFINES += -DMEM_DEFAULT_USE_DRAM 在 include/mem.h 中的具体定义如下 : #ifdef MEM_DEFAULT_USE_DRAM #define os_malloc os_malloc_dram #define os_zalloc os_zalloc_dram #define os_calloc os_calloc_dram #else #define os_malloc os_malloc_iram #define os_zalloc os_zalloc_iram #define os_calloc os_calloc_iram #endif Espressif 5! /! 153

22 ! 2. Non-OS SDK RAM 和 flash 访问必须是 4 字对 齐的, 请勿直接进 行行指针转换 请使 用 os_memcpy 或 其他 API 进 行行内存操作 Espressif 6! /! 153

23 3. 应 用程序接 口 (API) 3.1. 软件定时器器 以下软件定时器器接 口位于 /ESP8266_NONOS_SDK/include/osapi.h 请注意, 以下接 口使 用的定时器器由软件实现, 定时器器的函数在任务中被执 行行 因为任务可能被中断, 或者被其他 高优先级的任务延迟, 因此以下 os_timer 系列列的接 口并不不能保证定时器器精确执 行行 如果需要精确的定时, 例例如, 周期性操作某 GPIO, 请使 用硬件中断定时器器, 具体可参考 hw_timer.c, 硬件定时器器的执 行行函数在中断 里里被执 行行 注意 : 对于同 一个 timer,os_timer_arm 或 os_timer_arm_us 不不能重复调 用, 必须先 os_timer_disarm os_timer_setfn 必须在 timer 未使能的情况下调 用, 在 os_timer_arm 或 os_timer_arm_us 之前或者 os_timer_disarm 之后 os_timer_arm 使能毫秒级定时器器 void os_timer_arm ( os_timer_t *ptimer, uint32_t milliseconds, bool repeat_flag ) os_timer_t *ptimer: 定时器器结构 uint32_t milliseconds: 定时时间, 单位 :ms - 如未调 用 system_timer_reinit, 可 支持范围 5 ~ 0x68D7A3 - 如调 用了了 system_timer_reinit, 可 支持范围 100 ~ 0x689D0 bool repeat_flag: 定时器器是否重复 os_timer_disarm 取消定时器器定时 void os_timer_disarm (os_timer_t *ptimer) os_timer_t *ptimer: 定时器器结构 Espressif 7! /! 153

24 os_timer_setfn 设置定时器器回调函数 使 用定时器器, 必须设置回调函数 void os_timer_setfn( os_timer_t *ptimer, os_timer_func_t *pfunction, void *parg ) os_timer_t *ptimer: 定时器器结构 os_timer_func_t *pfunction: 定时器器回调函数 void *parg: 回调函数的 system_timer_reinit 注意 重新初始化定时器器, 当需要使 用微秒级定时器器时调 用 同时定义 USE_US_TIMER system_timer_reinit 在程序最开始调 用,user_init 的第 一句句 void system_timer_reinit (void) os_timer_arm_us 注意 使能微秒级定时器器 请定义 USE_US_TIMER, 并在 user_init 起始第 一句句, 先调 用 system_timer_reinit 最 高精度为 500 μs void os_timer_arm_us ( os_timer_t *ptimer, uint32_t microseconds, bool repeat_flag ) os_timer_t *ptimer: 定时器器结构 uint32_t microseconds: 定时时间, 单位 :μs, 最 小定时 0x64, 最 大可输 入 0xFFFFFFF bool repeat_flag: 定时器器是否重复 3.2. 硬件中断定时器器 以下硬件中断定时器器接 口位于 /ESP8266_NONOS_SDK/examples/driver_lib/ hw_timer.c 用户可根据 driver_lib 文件夹下的 readme.txt 文件使 用 Espressif 8! /! 153

25 注意 : 如果使 用 NMI 中断源, 且为 自动填装的定时器器, 调 用 hw_timer_arm 时 val 必须 大于 100 如果使 用 NMI 中断源, 那么该定时器器将为最 高优先级, 可打断其他 ISR 如果使 用 FRC1 中断源, 那么该定时器器法打断其他 ISR hw_timer.c 的接 口不不能跟 PWM 驱动接 口函数同时使 用, 因为 二者共 用了了同 一个硬件定时器器 硬件中断定时器器的回调, 请勿添加 ICACHE_FLASH_ATTR 宏 使 用 hw_timer.c 的接 口, 请勿调 用 wifi_set_sleep_type(light_sleep); 将 自动睡眠模式设置为 Light-sleep 因为 Light-sleep 在睡眠期间会停 CPU, 停 CPU 期间不不能响应 NMI 中断 hw_timer_init 初始化硬件 ISR 定时器器 void hw_timer_init ( FRC1_TIMER_SOURCE_TYPE source_type, u8 req ) FRC1_TIMER_SOURCE_TYPE source_type: 定时器器的 ISR 源 - FRC1_SOURCE: 使 用 FRC1 中断源 - NMI_SOURCE: 使 用 NMI 中断源 u8 req - 0: 不不 自动填装 ; - 1: 自动填装 hw_timer_arm 使能硬件中断定时器器 void hw_timer_arm (uint32 val) uint32 val: 定时时间 自动填装模式 : - 使 用 FRC1 中断源 FRC1_SOURCE, 取值范围 :50 ~ 0x μs; - 使 用 NMI 中断源 NMI_SOURCE, 取值范围 : 100 ~ 0x μs: 非 自动填装模式, 取值范围 :10 ~ 0x μs Espressif 9! /! 153

26 hw_timer_set_func 设置定时器器回调函数 使 用定时器器, 必须设置回调函数 注意回调函数前不不能添加 ICACHE_FLASH_ATTR 宏定义, 中断响应不不能存放在 Flash 中 void hw_timer_set_func (void (* user_hw_timer_cb_set)(void) ) void (* user_hw_timer_cb_set)(void): 定时器器回调函数, 时请勿添加 ICACHE_FLASH_ATTR 宏 硬件定时器器示例例 #define REG_READ(_r) (*(volatile uint32 *)(_r)) #define WDEV_NOW() REG_READ(0x3ff20c00) uint32 tick_now2 = 0; void hw_test_timer_cb(void) { static uint16 j = 0; j++; if( (WDEV_NOW() - tick_now2) >= ) { static u32 idx = 1; tick_now2 = WDEV_NOW(); os_printf("b%u:%d\n",idx++,j); j = 0; } } void ICACHE_FLASH_ATTR user_init(void) { hw_timer_init(frc1_source,1); hw_timer_set_func(hw_test_timer_cb); hw_timer_arm(100); } 3.3. 系统接 口 系统接 口位于 /ESP8266_NONOS_SDK/include/user_interface.h os_xxx 系列列接 口位于 /ESP8266_NONOS_SDK/include/osapi.h system_get_sdk_version 查询 SDK 版本信息 const char* system_get_sdk_version(void) Espressif 10! /! 153

27 示例例 SDK 版本信息 printf( SDK version: %s \n, system_get_sdk_version()); system_restore 注意 恢复出 厂设置 本接 口将清除以下接 口的设置, 恢复默认值 : wifi_station_set_auto_connect wifi_set_phy_mode wifi_softap_set_config 相关,wifi_station_set_config 相关,wifi_set_opmode 以及 #define AP_CACHE 记录的 AP 信息 恢复出 厂设置后, 请务必重新启动 system_restart, 再正常使 用 void system_restore(void) system_restart 注意 系统重启调 用本接 口后,ESP8266 模块并不不会 立刻重启, 请勿在本接 口之后调 用其他接 口 void system_restart(void) system_init_done_cb 注意示例例 在 user_init 中调 用, 注册系统初始化完成的回调函数 接 口 wifi_station_scan 必须在系统初始化完成后, 并且 Station 模式使能的情况下调 用 void system_init_done_cb(init_done_cb_t cb) init_done_cb_t cb: 系统初始化完成的回调函数 void to_scan(void) { wifi_station_scan(null,scan_done); } void user_init(void) { wifi_set_opmode(station_mode); system_init_done_cb(to_scan); } system_get_chip_id 查询芯 片 ID uint32 system_get_chip_id (void) Espressif 11! /! 153

28 芯 片 ID system_get_vdd33 测量量 VDD3P3 管脚 3 和 4 的电压值, 单位 :1/1024V system_get_vdd33 必须在 TOUT 管脚悬空的情况下使 用 注意 TOUT 管脚悬空的情况下,esp_init_data_default.bin (0 ~ 127 byte) 中的第 107 byte 为 vdd33_const, 必须设为 0xFF, 即 255 不不同 Wi-Fi 模式下, 例例如,Modem-sleep 模式或者普通 Wi-Fi 工作模式时,VDD33 的 测量量值会稍有差异 uint16 system_get_vdd33(void) VDD33 电压值 单位 :1/1024V system_adc_read 测量量 TOUT 管脚 6 的输 入电压, 单位 :1/1024V system_adc_read 必须在 TOUT 管脚接外部电路路情况下使 用,TOUT 管脚输 入电压范 围限定为 0 ~ 1.0V 注意 TOUT 管脚接外部电路路的情况下,esp_init_data_default.bin (0 ~ 127 byte) 中的第 107 byte vdd33_const, 必须设为 VDD3P3 管脚 3 和 4 上真实的电源电压, 且必须 小于 0xFF 第 107 byte vdd33_const 的单位是 0.1V, 有效取值范围是 [18, 36]; 当 vdd33_const 处于效范围 [0, 18) 或者 (36, 255) 时, 使 用默认值 3.3V 来优化 RF 电路路 工作状态 不不同 Wi-Fi 模式下, 例例如,Modem-sleep 模式或者普通 Wi-Fi 工作模式时,ADC 的测 量量值会稍有差异 若需要 高精度的 ADC, 请使 用 system_adc_read_fast 接 口 uint16 system_adc_read(void) TOUT 管脚 6 的输 入电压, 单位 :1/1024V Espressif 12! /! 153

29 system_adc_read_fast 快速 高精度的 ADC 采样 本接 口必须在关闭 Wi-Fi 的状态下使 用 如需进 行行连续测量量 ADC, 则还需要在关闭所有中断的状态下使 用 因此, 调 用 system_adc_read_fast 时, 不不能使 用 PWM 或者 NMI 类型的硬件定时器器 本接 口必须在 TOUT 管脚接外部电路路情况下使 用,TOUT 管脚输 入电压范围限定为 0 ~ 1.0V 注意 TOUT 管脚接外部电路路作为 ADC 输 入时,esp_init_data_default.bin (0 ~ 127 byte) 中的 [107] byte vdd33_const 必须 小于 0xFF [107] byte vdd33_const 的具体 用法如下 : - [107] byte = 0XFF 时, 内部测量量 VDD33,TOUT 管脚不不能作为外部 ADC 输 入 ; - [107] byte 有效取值范围是 [18, 36] 时, 单位是 0.1V, 设置为实际的 VDD33 电源电压, 优 化 RF 电路路 工作状态,TOUT 管脚可以作为外部 ADC 输 入 ; - [107] byte 有效取值范围是 [0, 18) 或者 (36, 255) 时, 使 用默认值 3.3V 作为电源电压来优 化 RF 电路路 工作状态,TOUT 管脚可以作为外部 ADC 输 入 void system_adc_read_fast(uint16 *adc_addr, uint16 adc_num, uint8 adc_clk_div) uint16 *adc_addr:adc 连续采样输出的地址指针 uint16 adc_num:adc 连续采样的点数, 输 入范围 [1, 65535] uint8 adc_clk_div:adc 工作时钟 = 80M/adc_clk_div, 输 入范围 [8, 32], 推荐值为 8 Espressif 13! /! 153

30 extern void system_adc_read_fast(uint16 *adc_addr, uint16 adc_num, uint8 adc_clk_div); os_timer_t timer; 示例例 void ICACHE_FLASH_ATTR ADC_TEST(void *p) { wifi_set_opmode(null_mode); ets_intr_lock(); uint16 adc_addr[10]; uint16 adc_num = 10; uint8 adc_clk_div = 8; uint32 i; //close interrupt system_adc_read_fast(adc_addr, adc_num, adc_clk_div); for(i=0; i<adc_num; i++) os_printf("i=%d, adc_v=%d\n", i, adc_addr[i]); ets_intr_unlock(); //open interrupt system_deep_sleep } os_timer_disarm(&timer); os_timer_setfn(&timer, ADC_TEST, NULL); os_timer_arm(&timer,1000,1); 注意 设置芯 片进 入 Deep-sleep 模式, 休眠设定时间后 自动唤醒, 唤醒后程序从 user_init 重新运 行行 硬件需要将 XPD_DCDC 通过 0Ω 电阻连接到 EXT_RSTB, 用作 Deep-sleep 唤醒 system_deep_sleep(0) 未设置唤醒定时器器, 可通过外部 GPIO 拉低 RST 脚唤醒 本接 口设置后, 芯 片并不不会 立刻进 入 Deep-sleep, 而是等待 Wi-Fi 底层安全关闭后, 才进 入 Deep-sleep 休眠 bool system_deep_sleep(uint64 time_in_us) uint64 time_in_us: 休眠时间, 单位 :μs time_in_us 的理理论最 大值可由公式 (time_in_us/cali)<<12 = 2^31-1 计算 - 其中 cali = system_rtc_clock_cali_proc(), 表示 RTC 的时钟周期,bit11 ~ bit0 为 小数部分, 受温度或电源电压变化 而偏移, 并不不精确, 详细可参考 system_rtc_clock_cali_proc 函数说明 由于计算并不不精确, 设置时传 入的 time_in_us 值需 小于理理论最 大值 True, 设置成功 False, 设置失败 Espressif 14! /! 153

31 system_deep_sleep_set_option 设置下 一次 Deep-sleep 唤醒后的 行行为, 如需调 用此 API, 必须在 system_deep_sleep 之 前调 用 默认 option 为 1 bool system_deep_sleep_set_option(uint8 option) uint8 option: 设置下 一次 Deep-sleep 唤醒后的 行行为 0: 由 esp_init_data_default.bin (0~127 byte) 的 byte 108 和 Deep-sleep 的次数 (deep_sleep_number, 上电时初始化为 0) 共同控制 Deep-sleep 唤醒后的 行行为, 以每 (byte ) 次 Deep-sleep 唤醒为周期循环 - 若 deep_sleep_number <= byte 108, 则 Deep-sleep 唤醒后不不进 行行任何 RF_CAL, 初始电流较 小 ; - 若 deep_sleep_number = byte , 则 Deep-sleep 唤醒后的 行行为与上电的 行行为 一致, 且将 deep_sleep_number 归零 ; 1:Deep-sleep 唤醒后的 行行为与上电的 行行为 一致 ; 2:Deep-sleep 唤醒后不不进 行行 RF_CAL, 初始电流较 小 ; 4:Deep-sleep 唤醒后不不打开 RF, 与 Modem-sleep 行行为 一致, 这样电流最 小, 但是设备唤醒后法发送和接收数据 true: 成功 false: 失败 system_phy_set_rfoption 设置此次 ESP8266 Deep-sleep 醒来, 是否打开 RF 本接 口只允许在 user_rf_pre_init 中调 用 注意 本接 口与 system_deep_sleep_set_option 相似, system_deep_sleep_set_option 在 Deep-sleep 前调 用, 本接 口在 Deep-sleep 醒来初 始化时调 用, 以本接 口设置为准 调 用本接 口前, 要求 至少调 用过 一次 system_deep_sleep_set_option void system_phy_set_rfoption(uint8 option) Espressif 15! /! 153

32 uint8 option: 设置下 一次 Deep-sleep 唤醒后的 行行为 0: 由 esp_init_data_default.bin (0~127 byte) 的 byte 108 和 Deep-sleep 的次数 (deep_sleep_number, 上电时初始化为 0) 共同控制 Deep-sleep 唤醒后的 行行为, 以每 (byte ) 次 Deep-sleep 唤醒为周期循环 - 若 deep_sleep_number <= byte 108, 则 Deep-sleep 唤醒后不不进 行行任何 RF_CAL, 初始电流较 小 ; - 若 deep_sleep_number = byte , 则 Deep-sleep 唤醒后的 行行为与上电的 行行为 一致, 且将 deep_sleep_number 归零 ; 1:Deep-sleep 唤醒后的 行行为与上电的 行行为 一致 ; 2:Deep-sleep 唤醒后不不进 行行 RF_CAL, 初始电流较 小 ; 4:Deep-sleep 唤醒后不不打开 RF, 与 Modem-sleep 行行为 一致, 这样电流最 小, 但是设备唤醒后法发送和接收数据 system_phy_set_powerup_option 设置上电时 RF 初始化的 行行为, 默认为 option 0 void system_phy_set_powerup_option(uint8 option) uint8 option:power up 时,RF 初始化的 行行为 0: 由 esp_init_data_default.bin (0 ~ 127 byte) byte 114 控制 RF 初始化 行行为, 详细可参考 ESP8266 SDK 入 门指南 1:RF 初始化仅做 VDD33 和 TX power CAL, 耗时约 18 ms, 初始电流较 小 2:RF 初始化仅做 VDD33 校准, 耗时约 2 ms, 初始电流最 小 3:RF 初始化进 行行全部 RF CAL, 耗时约 200 ms, 初始电流较 大 system_phy_set_max_tpw 设置 RF TX Power 最 大值, 单位 :0.25 dbm void system_phy_set_max_tpw(uint8 max_tpw) uint8 max_tpw:rf Tx Power 的最 大值, 可参考 esp_init_data_default.bin (0 ~ 127 byte) 的第 34 byte target_power_qdb_0 设置, 单位 :0.25 dbm, 范围 [0, 82] system_phy_set_tpw_via_vdd33 根据改变的 VDD33 电压值, 重新调整 RF TX Power, 单位 :1/1024V 在 TOUT 管脚悬空的情况下,VDD33 电压值可通过 system_get_vdd33 测量量获得 注意 在 TOUT 管脚接外部电路路情况下, 不不可使 用 system_get_vdd33 测量量 VDD33 电压 值 Espressif 16! /! 153

33 void system_phy_set_tpw_via_vdd33(uint16 vdd33) uint16 vdd33: 重新测量量的 VDD33 值, 单位 :1/1024V, 有效值范围 :[1900, 3300] system_set_os_print 默认值 开关打印 log void system_set_os_print (uint8 onoff) uint8 onoff 0: 打印关 ; 1: 打印开打印开 system_print_meminfo 打印系统内存空间分配, 打印信息包括 data/rodata/bss/heap void system_print_meminfo (void) system_get_free_heap_size 查询系统剩余可 用 heap 区空间 大 小 uint32 system_get_free_heap_size(void) uint32: 可 用 heap 空间 大 小 system_os_task 创建系统任务, 最多 支持创建 3 个任务, 优先级分别为 0/1/2 bool system_os_task( os_task_t task, uint8 prio, os_event_t *queue, uint8 qlen ) os_task_t task: 任务函数 uint8 prio: 任务优先级, 可为 0/1/2;0 为最低优先级 这表示最多只 支持建 立 3 个任务 os_event_t *queue: 消息队列列指针 uint8 qlen: 消息队列列深度 Espressif 17! /! 153

34 示例例 true: 成功 false: 失败 #define SIG_RX 0 #define TEST_QUEUE_LEN 4 os_event_t *testqueue; void test_task (os_event_t *e) { switch (e->sig) { case SIG_RX: os_printf(sig_rx %c/n, (char)e->par); break; default: break; } } void task_init(void) { testqueue=(os_event_t *)os_malloc(sizeof(os_event_t)*test_queue_len); system_os_task(test_task,user_task_prio_0,testqueue,test_queue_len); } system_os_post 向任务发送消息 bool system_os_post ( uint8 prio, os_signal_t sig, os_param_t par ) uint8 prio: 任务优先级, 与建 立时的任务优先级对应 os_signal_t sig: 消息类型 os_param_t par: 消息 true: 成功 false: 失败结合上 一节 void task_post(void) { system_os_post(user_task_prio_0, SIG_RX, a ); 的示例例 } 打印输出 sig_rx a system_get_time 查询系统时间, 单位 :μs uint32 system_get_time(void) 系统时间, 单位 :μs Espressif 18! /! 153

35 system_get_rtc_time 示例例 注意 查询 RTC 时间, 单位 :RTC 时钟周期例例如 system_get_rtc_time 10( 表示 10 个 RTC 周期 ), system_rtc_clock_cali_proc 5.75( 表示 1 个 RTC 周期为 5.75 μs), 则实际时间为 10 x 5.75 = 57.5 μs system_restart 时, 系统时间归零, 但是 RTC 时间仍然继续 但是如果外部硬件通过 EXT_RST 脚或者 CHIP_EN 脚, 将芯 片复位后 ( 包括 Deep-sleep 定时唤醒的情况 ), RTC 时钟会复位 具体如下 : 外部复位 EXT_RST:RTC memory 不不变,RTC timer 寄存器器从零计数 看 门狗复位 :RTC memory 不不变,RTC timer 寄存器器不不变 system_restart:rtc memory 不不变,RTC timer 寄存器器不不变 电源上电 :RTC memory 随机值,RTC timer 寄存器器从零计数 CHIP_EN 复位 :RTC memory 随机值,RTC timer 寄存器器从零计数 uint32 system_get_rtc_time(void) RTC 时间 system_rtc_clock_cali_proc 查询 RTC 时钟周期 RTC 时钟周期含有 小数部分 注意示例例 RTC 时钟周期会随温度或电源电压变化发 生偏移, 因此 RTC 时钟适 用于在精度可接受的范围内进 行行计时, 建议最多每分钟调 用 一次即可 uint32 system_rtc_clock_cali_proc(void) RTC 时钟周期, 单位 :μs,bit11 ~ bit0 为 小数部分 os_printf( clk cal : %d \r\n,system_rtc_clock_cali_proc()>>12); 详细 RTC 示例例请 见附录 system_rtc_mem_write 注意 由于 Deep-sleep 时, 仅 RTC 仍在 工作, 用户如有需要, 可将数据存 入 RTC memory 中 提供 如下图中的 user data 段共 512 bytes 供 用户存储数据 < system data > < user data > 256 bytes 512 bytes RTC memory 只能 4 字节整存整取, 函数中 des_addr 为 block number, 每 block 4 字 节, 因此若写 入上图 user data 区起始位置,des_addr 为 256/4 = 64,save_size 为存 入数据 的字节数 Espressif 19! /! 153

36 bool system_rtc_mem_write ( uint32 des_addr, void * src_addr, uint32 save_size ) uint32 des_addr: 写 入 rtc memory 的位置,des_addr >=64 void * src_addr: 数据指针 uint32 save_size: 数据 长度, 单位 : 字节 true: 成功 false: 失败 system_rtc_mem_read 读取 RTC memory 中的数据, 提供如下图中 user data 段共 512 bytes 给 用户存储数据 < system data > < user data > 256 bytes 512 bytes RTC memory 只能 4 字节整存整取, 函数中 des_addr 为 block number, 每 block 4 字 注意 节, 因此若写 入上图 user data 区起始位置,des_addr 为 256/4 = 64,save_size 为存 入数据 的字节数 bool system_rtc_mem_read ( uint32 src_addr, void * des_addr, uint32 save_size ) uint32 des_addr: 写 入 rtc memory 的位置,des_addr >=64 void * src_addr: 数据指针 uint32 save_size: 数据 长度, 单位 : 字节 true: 成功 false: 失败 system_uart_swap UART0 转换 将 MTCK 作为 UART0 RX,MTDO 作为 UART0 TX 硬件上也从 MTDO (U0RTS) 和 MTCK (U0CTS) 连出 UART0, 从 而避免上电时从 UART0 打印出 ROM log void system_uart_swap (void) system_uart_de_swap 取消 UART0 转换, 仍然使 用原有 UART0, 而不不是将 MTCK MTDO 作为 UART0 void system_uart_de_swap (void) Espressif 20! /! 153

37 system_get_boot_version 读取 boot 版本信息 uint8 system_get_boot_version (void) boot 版本信息 注意如果 boot 版本号 >= 3 时, 支持 boot 增强模式, 详 见 system_restart_enhance system_get_userbin_addr 读取当前正在运 行行的 user bin(user1.bin 或者 user2.bin) 的存放地址 uint32 system_get_userbin_addr (void) 正在运 行行的 user bin 的存放地址 system_get_boot_mode 注意 查询 boot 模式 uint8 system_get_boot_mode (void) #define SYS_BOOT_ENHANCE_MODE 0 #define SYS_BOOT_NORMAL_MODE 1 boot 增强模式 : 支持跳转到任意位置运 行行程序 ; boot 普通模式 : 仅能跳转到固定的 user1.bin( 或 user2.bin) 位置运 行行 system_restart_enhance 重启系统, 进 入 boot 增强模式 bool system_restart_enhance( uint8 bin_type, uint32 bin_addr ) uint8 bin_type:bin 类型 - #define SYS_BOOT_NORMAL_BIN 0 // user1.bin 或者 user2.bin - #define SYS_BOOT_TEST_BIN 1 // 向乐鑫申请的 test bin uint32 bin_addr:bin 的起始地址 true: 成功 false: 失败 Espressif 21! /! 153

38 注意 SYS_BOOT_TEST_BIN 用于量量产测试, 用户可以向乐鑫申请获得 system_update_cpu_req 注意 设置 CPU 频率 默认为 80 MHz 系统总线时钟频率始终为 80 MHz, 不不受 CPU 频率切换的影响 UART SPI 等外设频率由系统总线时钟分频 而来, 因此也不不受 CPU 频率切换的影响 bool system_update_cpu_freq(uint8 freq) uint8 freq:cpu 频率 #define SYS_CPU_80MHz 80 #define SYS_CPU_160MHz 160 true: 成功 false: 失败 system_get_cpu_freq 查询 CPU 频率 uint8 system_get_cpu_freq(void) CPU 频率, 单位 :MHz system_get_flash_size_map 结构体 查询当前的 Flash size 和 Flash map Flash map 对应编译时的选项, 详细介绍请参考 ESP8266 SDK 入 门指南 enum flash_size_map { FLASH_SIZE_4M_MAP_256_256 = 0, FLASH_SIZE_2M, FLASH_SIZE_8M_MAP_512_512, FLASH_SIZE_16M_MAP_512_512, FLASH_SIZE_32M_MAP_512_512, FLASH_SIZE_16M_MAP_1024_1024, FLASH_SIZE_32M_MAP_1024_1024, FLASH_SIZE_64M_MAP_1024_1024, FLASH_SIZE_128M_MAP_1024_1024, }; enum flash_size_map system_get_flash_size_map(void) flash map Espressif 22! /! 153

39 system_get_rst_info 结构体 查询当前启动的信息 enum rst_reason { REANSON_DEFAULT_RST = 0, // normal startup by power on REANSON_WDT_RST = 1, // hardware watch dog reset // exception reset, GPIO status won t change REANSON_EXCEPTION_RST = 2, // software watch dog reset, GPIO status won t change REANSON_SOFT_WDT_RST = 3, // software restart,system_restart, GPIO status won t change REANSON_SOFT_RESTART = 4, REANSON_DEEP_SLEEP_AWAKE = 5, // wake up from deep-sleep REANSON_EXT_SYS_RST = 6, // external system reset }; struct rst_info { uint32 reason; // enum rst_reason uint32 exccause; uint32 epc1; // the address that error occurred uint32 epc2; uint32 epc3; uint32 excvaddr; uint32 depc; }; struct rst_info* system_get_rst_info(void) 启动的信息 system_soft_wdt_stop 注意 关闭软件看 门狗请勿将软件看 门狗关闭太 长时间 ( 小于 5s), 否则将触发硬件看 门狗复位 void system_soft_wdt_stop(void) system_soft_wdt_restart 注意 重启软件看 门狗 仅 支持在软件看 门狗关闭 system_soft_wdt_stop 的情况下, 调 用本接 口 Espressif 23! /! 153

40 void system_soft_wdt_restart(void) system_soft_wdt_feed 注意 喂软件看 门狗仅 支持在软件看 门狗开启的情况下, 调 用本接 口 void system_soft_wdt_feed(void) system_show_malloc 注意 打印 目前所分配的堆空间所有内存块, 包括分配该内存块的 文件名 行行号和分配 大 小 在怀疑有内存泄露露时, 可以调 用本接 口查看当前内存状态 在 user_config.h 定义 #define MEMLEAK_DEBUG 参考 ESP8266_NONOS_SDK\included\mem.h 开始位置的注释使 用 泄露露的内存 一般在打印结果中, 但打印结果中的内存不不保证 一定是泄露露的内存 本接 口仅 用于调试, 法确保使 用本接 口后, 程序能继续正常执 行行, 因此请勿在正常运 行行情 况下, 调 用本接 口 void system_show_malloc(void) os_memset 封装 C 语 言函数, 在 一段内存块中填充某个给定值 os_memset(void *s, int ch, size_t n) void *s: 内存块指针 int ch: 填充值 size_t n: 填充 大 小 示例例 uint8 buffer[32]; os_memset(buffer, 0, sizeof(buffer)); Espressif 24! /! 153

41 os_memcpy 封装 C 语 言函数, 内存拷 贝 os_memcpy(void *des, void *src, size_t n) void *des: 目标内存块指针 void *src: 源内存块指针 size_t n: 拷 贝内存 大 小 示例例 uint8 buffer[4] = {0}; os_memcpy(buffer, abcd, 4); os_strlen 示例例 封装 C 语 言函数, 计算字符串串 长度 os_strlen(char *s) char *s: 字符串串字符串串 长度 char *ssid = ESP8266 ; os_memcpy(softap_config.ssid, ssid, os_strlen(ssid)); os_printf 注意示例例 格式化输出, 打印字符串串 本接 口默认从 UART 0 打印 IOT_Demo 中的 uart_init 可以设置波特率, 将 os_printf 改为从 UART 1 打印 :os_install_putc1((void *)uart1_write_char); 请勿调 用本接 口打印超过 125 字节的数据, 或者频繁连续调 用本接 口打印, 否则可能会丢失部分待打印数据 void os_printf(const char *s) const char *s: 字符串串 os_printf( SDK version: %s \n, system_get_sdk_version()); os_bzero 置字符串串 p 的前 n 个字节为零且包含 \0 void os_bzero(void *p, size_t n) void *p: 要置零的数据的起始地址 size_t n: 要置零的数据字节数 Espressif 25! /! 153

42 os_delay_us 延时函数 最 大值 μs void os_delay_us(uint16 us) uint16 us: 延时时间 os_install_putc1 示例例 注册打印接 口函数 void os_install_putc1(void(*p)(char c)) void(*p)(char c): 打印接 口函数指针参考 UART.c,uart_init 中的 os_install_putc1((void *)uart1_write_char) 将 os_printf 改为从 UART 1 打印 否则,os_printf 默认从 UART 0 打印 os_random 获取随机数 unsigned long os_random(void) 随机数 os_get_random 示例例 获取指定 长度的随机数 int os_get_random(unsigned char *buf, size_t len) unsigned char *buf: 获得的随机数 size_t len: 随机数的字节 长度 true: 成功 false: 失败 int ret = os_get_random((unsigned char *)temp, 7); os_printf("ret %d, value 0x%08x%08x\n\r", ret, temp[1], temp[0]); user_rf_cal_sector_set 用户 自定义 RF_CAL 存放在 Flash 的扇区号 Espressif 26! /! 153

43 用户必须在程序中实现此函数, 否则编译链接时会报错 但 用户程序需调 用此函数,SDK 底层会调 用它, 将 RF_CAL 保存在 用户指定的 Flash 扇区 里里, 这将占 用 用户区的 一个扇区 注意 SDK 预留留的 4 个扇区的系统区已经使 用, 因此 RF_CAL 需要占 用到 用户区的空 间, 由 用户通过此函数设置 一个可 用扇区供 SDK 底层使 用 建议整个系统需要初始化时, 或需要重新进 行行 RF_CAL 时, 烧录 blank.bin 初始化 RF_CAL 参 数区, 并烧录 esp_init_data.bin 注意,esp_init_data.bin 至少需要烧录 一次 uint32 user_rf_cal_sector_set(void) 存储 RF_CAL 的 Flash 扇区号 将 RF 设置存放在 Flash 倒数第 5 个扇区 uint32 user_rf_cal_sector_set(void) { enum flash_size_map size_map = system_get_flash_size_map(); uint32 rf_cal_sec = 0; switch (size_map) { case FLASH_SIZE_4M_MAP_256_256: rf_cal_sec = 128-5; break; case FLASH_SIZE_8M_MAP_512_512: rf_cal_sec = 256-5; break; 示例例 case FLASH_SIZE_16M_MAP_512_512: case FLASH_SIZE_16M_MAP_1024_1024: rf_cal_sec = 512-5; break; case FLASH_SIZE_32M_MAP_512_512: case FLASH_SIZE_32M_MAP_1024_1024: rf_cal_sec = 512-5; break; case FLASH_SIZE_64M_MAP_1024_1024: rf_cal_sec = ; break; case FLASH_SIZE_128M_MAP_1024_1024: rf_cal_sec = ; break; } default: rf_cal_sec = 0; break; } return rf_cal_sec; Espressif 27! /! 153

44 system_deep_sleep_instant 设置芯 片 立刻进 入 Deep-sleep 模式, 休眠设定时间后 自动唤醒, 唤醒后程序从 user_init 重新运 行行 硬件需要将 XPD_DCDC 通过 0Ω 电阻连接到 EXT_RSTB, 用作 Deep-sleep 唤醒 system_deep_sleep_instant(0) 未设置唤醒定时器器, 可通过外部 GPIO 拉低 RST 脚 注意 唤醒 本接 口设置后, 芯 片 立刻进 入 Deep-sleep 休眠, 不不会等待 Wi-Fi 底层安全关 闭 如需等待 Wi-Fi 安全关闭, 可使 用接 口 system_deep_sleep bool system_deep_sleep_instant(uint64 time_in_us) uint64 time_in_us: 休眠时间, 单位 :μs time_in_us 的理理论最 大值可由公式 (time_in_us/cali)<<12 = 2^32-1 计算 - 其中 cali = system_rtc_clock_cali_proc(), 表示 RTC 的时钟周期,bit11 ~ bit0 为 小数部分, 受温度或电源电压变化 而偏移, 并不不精确, 详细可参考 system_rtc_clock_cali_proc 函数说明 由于计算并不不精确, 设置时传 入的 time_in_us 值需 小于理理论最 大值 True, 设置成功 False, 设置失败 system_partition_table_regist 注册 partition table 注意 本接 口必须在 user_pre_init 中调 用注册, 如果注册失败, 请检查 partition table 的 定义 示例例可参考 ESP8266_NONOS_SDK/examples/IoT_Demo/user/user_main.c bool system_partition_table_regist( const partition_item_t* partition_table, uint32_t partition_num, ) uint32_t map const partition_item_t* partition_table: 分区表 uint32_t partition_num: 分区数 目 uint32_t map:flash map; 必须与编译烧录时选择的 flash map 一致, 否则将会启动异常 ; 建议直接传 入宏 SPI_FLASH_SIZE_MAP, 它是系统在编译时记录的 flash map 值 True,partition table 注册成功 False,partition table 注册失败 system_partition_get_ota_partition_size 查询 ota partition 的 大 小 Espressif 28! /! 153

45 注意 ota partition 是 用于存放 user1.bin 或者 user2.bin 的 flash 分区 uint32_t system_partition_get_ota_partition_size(void) - ota partition 的 大 小 system_partition_get_item 查询指定类型的 partition 信息 bool system_partition_get_item(partition_type_t type, partition_item_t* partition_item) partition_type_t type: 分区类型 partition_item_t* partition_item: 查询到的分区信息 True, 查询成功 False, 查询失败 3.4. SPI Flash 接 口 SPI Flash 接 口位于 /ESP8266_NONOS_SDK/include/spi_flash.h system_param_xxx 接 口位于 /ESP8266_NONOS_SDK/include/user_interface.h 关于 SPI Flash 读写操作, 详 见 文档 ESP8266 Flash 读写说明 spi_flash_get_id 查询 SPI Flash 的 ID uint32 spi_flash_get_id (void) spi flash id spi_flash_erase_sector 擦除 Flash 扇区 SpiFlashOpResult spi_flash_erase_sector (uint16 sec) uint16 sec: 扇区号, 从扇区 0 开始计数, 每扇区 4 KB typedef enum{ SPI_FLASH_RESULT_OK, SPI_FLASH_RESULT_ERR, SPI_FLASH_RESULT_TIMEOUT } SpiFlashOpResult; Espressif 29! /! 153

46 spi_flash_write 写 入数据到 Flash Flash 读写必须 4 字节对 齐 SpiFlashOpResult spi_flash_write ( uint32 des_addr, uint32 *src_addr, uint32 size ) uint32 des_addr: 写 入 Flash 目的地址 uint32 *src_addr: 写 入数据的指针 uint32 size: 数据 长度, 单位 byte, 必须 4 字节对 齐进 行行读写 typedef enum{ SPI_FLASH_RESULT_OK, SPI_FLASH_RESULT_ERR, SPI_FLASH_RESULT_TIMEOUT } SpiFlashOpResult; spi_flash_read 从 Flash 读取数据 Flash 读写必须 4 字节对 齐 SpiFlashOpResult spi_flash_read( uint32 src_addr, uint32 * des_addr, uint32 size ) uint32 des_addr: 写 入 Flash 目的地址 uint32 *des_addr: 存放读取到数据的指针 uint32 size: 数据 长度, 单位 byte, 必须 4 字节对 齐进 行行读写 typedef enum { SPI_FLASH_RESULT_OK, SPI_FLASH_RESULT_ERR, SPI_FLASH_RESULT_TIMEOUT } SpiFlashOpResult; uint32 value; 示例例 uint8 *addr = (uint8 *)&value; spi_flash_read(0x3e * SPI_FLASH_SEC_SIZE, (uint32 *)addr, 4); os_printf("0x3e sec:%02x%02x%02x%02x\r\n", addr[0], addr[1], addr[2], addr[3]); Espressif 30! /! 153

47 system_param_save_with_protect 使 用带读写保护机制的 方式, 写 入数据到 Flash Flash 读写必须 4 字节对 齐 注意 Flash 读写保护机制 : 使 用 3 个 sector(4 KB 每 sector) 保存 1 个 sector 的数据,sector 0 和 sector 1 互相为备份, 交替保存数据,sector 2 作为 flag sector, 指示最新的数据保存在 sector 0 还是 sector 1 关于 SPI Flash 读写操作, 详 见 文档 ESP8266 Flash 读写说明 bool system_param_save_with_protect ( uint16 start_sec, void *param, uint16 len ) uint16 start_sec: 读写保护机制使 用的 3 个 sector 的起始 sector 0 值 例例如,IOT_Demo 中可使 用 0x3D000 开始的 3 个 sector(3 4 KB) 建 立读写保护机制, 则 start_sec 传 0x3D void *param: 写 入数据的指针 uint16 len: 数据 长度, 不不能超过 1 个 sector 大 小, 即 true: 成功 false: 失败 system_param_load 使 用带读写保护机制的 方式, 写 入数据到 Flash Flash 读写必须 4 字节对 齐 注意 Flash 读写保护机制 : 使 用 3 个 sector(4 KB 每 sector) 保存 1 个 sector 的数据,sector 0 和 sector 1 互相为备份, 交替保存数据,sector 2 作为 flag sector, 指示最新的数据保存在 sector 0 还是 sector 1 关于 SPI Flash 读写操作, 详 见 文档 ESP8266 Flash 读写说明 bool system_param_load ( uint16 start_sec, uint16 offset, void *param, uint16 len ) uint16 start_sec: 读写保护机制使 用的 3 个 sector 的起始 sector 0 值 例例如,IOT_Demo 中可使 用 0x3D000 开始的 3 个 sector(3 4 KB) 建 立读写保护机制, 则 start_sec 传 0x3D, 请勿传 入 0x3E 或者 0x3F uint16 offset: 需读取数据, 在 sector 中的偏移地址 void *param: 读取数据的指针 uint16 len: 数据 长度, 不不能超过 1 个 sector 大 小, 即 offset+len 4*1024 Espressif 31! /! 153

48 true: 成功 false: 失败 spi_flash_set_read_func 注意 注册 用户 自定义的 SPI Flash 读取接 口函数 仅 支持在 SPI overlap 模式下使 用, 请 用户参考 ESP8266_NONOS_SDK\driver_lib\driver\spi_overlap.c void spi_flash_set_read_func (user_spi_flash_read read) ) typedef SpiFlashOpResult (*user_spi_flash_read)( SpiFlashChip *spi, uint32 src_addr, uint32 * des_addr, uint32 size spi_flash_erase_protect_enable 使能 flash 擦写保护 使能后, 将保护 flash 不不会误操作擦写了了正在运 行行的应 用程序 bool spi_flash_erase_protect_enable(void) True: 设置成功 False: 设置失败 spi_flash_erase_protect_disable 关闭 flash 擦写保护 bool spi_flash_erase_protect_disable(void) True: 设置成功 False: 设置失败 Espressif 32! /! 153

49 3.5. Wi-Fi 接 口 Wi-Fi 接 口位于 /ESP8266_NONOS_SDK/include/user_interface.h wifi_station_xxx 系列列接 口以及 ESP8266 Station 相关的设置 查询接 口, 请在 ESP8266 Station 使能的情况下调 用 ; wifi_softap_xxx 系列列接 口以及 ESP8266 SoftAP 相关的设置 查询接 口, 请在 ESP8266 SoftAP 使能的情况下调 用 ESP8266 station 支持的认证类型有 :OPEN,WEP,WPAPSK,WPA2PSK; 支持的加密 方式有 :AUTO,TKIP,AES,WEP ESP8266 softap 支持的认证类型有 :OPEN,WPAPSK,WPA2PSK; 支持的加密 方式有 :AUTO,TKIP,AES; 但 group key 加密 方式, 只 支持 TKIP, 不不 支持 AES 后 文的 Flash 系统区 位于 Flash 的最后 16 KB wifi_get_opmode 查询 Wi-Fi 当前 工作模式 uint8 wifi_get_opmode (void) Wi-Fi 工作模式 : 0x01:Station 模式 0x02:SoftAP 模式 0x03:Station+SoftAP 模式 wifi_get_opmode_default 查询保存在 Flash 中的 Wi-Fi 工作模式设置 uint8 wifi_get_opmode_default (void) Wi-Fi 工作模式 : 0x01:Station 模式 0x02:SoftAP 模式 0x03:Station+SoftAP 模式 wifi_set_opmode 设置 Wi-Fi 工作模式 (Station,SoftAP 或者 Station+SoftAP), 并保存到 Flash 默认为 SoftAP 模式 Espressif 33! /! 153

50 注意 ESP8266_NONOS_SDK_V0.9.2 以及之前版本, 设置之后需要调 用 system_restart() 重启 生效 ; ESP8266_NONOS_SDK_V0.9.2 之后的版本, 不不需要重启, 即时 生效 本设置如果与原设置不不同, 会更更新保存到 Flash 系统区 bool wifi_set_opmode (uint8 opmode) uint8 opmode:wi-fi 工作模式 0x01:Station 模式 0x02:SoftAP 模式 0x03:Station+SoftAP 模式 true: 成功 false: 失败 wifi_set_opmode_current 设置 Wi-Fi 工作模式 (Station,SoftAP 或者 Station + SoftAP), 不不保存到 Flash bool wifi_set_opmode_current (uint8 opmode) uint8 opmode:wi-fi 工作模式 0x01:Station 模式 0x02:SoftAP 模式 0x03:Station+SoftAP 模式 true: 成功 false: 失败 wifi_station_get_config 查询 Wi-Fi Station 接 口的当前配置 bool wifi_station_get_config (struct station_config *config) struct station_config *config:wi-fi Station 接 口指针 true: 成功 false: 失败 wifi_station_get_config_default 查询 Wi-Fi Station 接 口保存在 Flash 中的配置 bool wifi_station_get_config_default (struct station_config *config) struct station_config *config:wi-fi Station 接 口指针 true: 成功 false: 失败 Espressif 34! /! 153

51 wifi_station_set_config 设置 Wi-Fi Station 接 口的配置, 并保存到 Flash 请在 ESP8266 Station 使能的情况下, 调 用本接 口 如果 wifi_station_set_config 在 user_init 中调 用, 则 ESP8266 Station 接 口会在系统初 始化完成后, 自动连接 AP( 路路由 ), 需再调 用 wifi_station_connect 注意 否则, 需要调 用 wifi_station_connect 连接 AP( 路路由 ) station_config.bssid_set 一般设置为 0, 仅当需要检查 AP 的 MAC 地址时 ( 多 用于有重 名 AP 的情况下 ) 设置为 1 本设置如果与原设置不不同, 会更更新保存到 Flash 系统区 bool wifi_station_set_config (struct station_config *config) struct station_config *config:wi-fi Station 接 口配置指针 true: 成功 false: 失败 void ICACHE_FLASH_ATTR user_set_station_config(void) { char ssid[32] = SSID; char password[64] = PASSWORD; struct station_config stationconf; stationconf.bssid_set = 0; //need not check MAC address of AP 示例例 os_memcpy(&stationconf.ssid, ssid, 32); os_memcpy(&stationconf.password, password, 64); wifi_station_set_config(&stationconf); } void user_init(void) { wifi_set_opmode(stationap_mode); //Set softap + station mode } user_set_station_config(); wifi_station_set_config_current 设置 Wi-Fi Station 接 口的配置, 不不保存到 Flash Espressif 35! /! 153

52 请在 ESP8266 Station 使能的情况下, 调 用本接 口 如果 wifi_station_set_config 在 user_init 中调 用, 则 ESP8266 Station 接 口会在系统初始化完成后, 自动连接 AP( 路路由 ), 需再调 用 wifi_station_connect 注意 否则, 需要调 用 wifi_station_connect 连接 AP( 路路由 ) station_config.bssid_set 一般设置为 0, 仅当需要检查 AP 的 MAC 地址时 ( 多 用于有重 名 AP 的情况下 ) 设置为 1 本设置如果与原设置不不同, 会更更新保存到 Flash 系统区 bool wifi_station_set_config_current (struct station_config *config) struct station_config *config:wi-fi Station 接 口配置指针 true: 成功 false: 失败 wifi_station_set_cert_key 不不建议使 用本接 口, 请使 用 wifi_station_set_enterprise_cert_key 代替 设置 ESP8266 Wi-Fi Station 接 口连接 WPA2-ENTERPRISE AP 使 用的证书 支持 WPA2-ENTERPRISE AP 需占 用 26 KB 以上的内存, 调 用本接 口时请注意内存是否 足够 目前 WPA2-ENTERPRISE 只 支持 非加密的私钥 文件和证书 文件, 且仅 支持 PEM 格式 - 支持的证书 文件头信息为 : BEGIN CERTIFICATE 注意 - 支持的私钥 文件头信息为 : BEGIN RSA PRIVATE KEY 或者 BEGIN PRIVATE KEY 请在连接 WPA2-ENTERPRISE AP 之前调 用本接 口设置私钥 文件和证书 文件, 在成功连接 AP 后先调 用 wifi_station_clear_cert_key 清除内部状态, 应 用层再释放私钥 文件和证书 文件信息 如果遇到加密的私钥 文件, 请使 用 openssl pkey 命令改为 非加密 文件使 用, 或者使 用 openssl rsa 等命令, 对某些私钥 文件进 行行加密 - 非加密的转换( 或起始 TAG 转化 ) bool wifi_station_set_cert_key ( uint8 *client_cert, int client_cert_len, uint8 *private_key, int private_key_len, uint8 *private_key_passwd, int private_key_passwd_len,) uint8 *client_cert: 十六进制数组的证书指针 int client_cert_len: 证书 长度 uint8 *private_key: 十六进制数组的私钥指针, 暂不不 支持超过 2048 的私钥 int private_key_len: 私钥 长度, 请勿超过 2048 uint8 *private_key_passwd: 私钥的提取密码, 目前暂不不 支持, 请传 入 NULL int private_key_passwd_len: 提取密码的 长度, 目前暂不不 支持, 请传 入 0 Espressif 36! /! 153

53 示例例 0: 成功 非 0: 失败假设私钥 文件的信息为 BEGIN PRIVATE KEY 那么对应的数组为 :uint8 key[]={0x2d, 0x2d, 0x2d, 0x2d, 0x2d, 0x42, 0x45, 0x47, 0x00 }; 即各字符的 ASCII 码, 请注意, 数组必须添加 0x00 作为结尾 wifi_station_clear_cert_key 不不建议使 用本接 口, 请使 用 wifi_station_clear_enterprise_cert_key 代替 释放连接 WPA2-ENTERPRISE AP 使 用证书占 用的资源, 并清除相关状态 void wifi_station_clear_cert_key (void) wifi_station_set_username 不不建议使 用本接 口, 请使 用 wifi_station_set_enterprise_username 代替 设置连接 WPA2-ENTERPRISE AP 时,ESP8266 Station 的 用户名 int wifi_station_set_username (uint8 *username, int len) uint8 *username: 用户名称 int len: 名称 长度 0: 成功其他 : 失败 wifi_station_clear_username 不不建议使 用本接 口, 请使 用 wifi_station_clear_enterprise_username 代替 释放连接 WPA2-ENTERPRISE AP 设置 用户名占 用的资源, 并清除相关状态 void wifi_station_clear_username (void) wifi_station_connect 注意 ESP8266 Wi-Fi Station 接 口连接 AP 请勿在 user_init 中调 用本接 口, 请在 ESP8266 Station 使能并初始化完成后调 用 ; 如果 ESP8266 已经连接某个 AP, 请先调 用 wifi_station_disconnect 断开上 一次连接 bool wifi_station_connect (void) Espressif 37! /! 153

54 true: 成功 false: 失败 wifi_station_disconnect 注意 ESP8266 Wi-Fi Station 接 口从 AP 断开连接请勿在 user_init 中调 用本接 口, 本接 口必须在系统初始化完成后, 并且 ESP8266 Station 接 口使能的情况下调 用 bool wifi_station_disconnect (void) true: 成功 false: 失败 wifi_station_get_connect_status 注意 查询 ESP8266 Wi-Fi Station 接 口连接 AP 的状态 若为特殊应 用场景 : 调 用 wifi_station_set_reconnect_policy 关闭重连, 且未调 用 wifi_set_event_handler_cb 注册 Wi-Fi 事件回调, 则本接 口失效, 法准确获得连接状态 uint8 wifi_station_get_connect_status (void) enum{ STATION_IDLE = 0, STATION_CONNECTING, STATION_WRONG_PASSWORD, STATION_NO_AP_FOUND, STATION_CONNECT_FAIL, STATION_GOT_IP }; wifi_station_scan 注意结构体 获取 AP 的信息 请勿在 user_init 中调 用本接 口, 本接 口必须在系统初始化完成后, 并且 ESP8266 Station 接 口使能的情况下调 用 bool wifi_station_scan (struct scan_config *config, scan_done_cb_t cb); struct scan_config { uint8 *ssid; // AP s ssid uint8 *bssid; // AP s bssid uint8 channel; //scan a specific channel uint8 show_hidden; //scan APs of which ssid is hidden. wifi_scan_type_t scan_type; // scan type, active or passive wifi_scan_time_t scan_time; // scan time per channel }; Espressif 38! /! 153

55 struct scan_config *config: 扫描 AP 的配置 - 若 config==null: 扫描获取所有可 用 AP 的信息 - 若 config.ssid==null && config.bssid==null && config.channel!=null:esp8266 Station 接 口扫描获取特定信道上的 AP 信息 - 若 config.ssid!=null && config.bssid==null && config.channel==null:esp8266 Station 接 口扫描获取所有信道上的某特定名称 AP 的信息 scan_done_cb_t cb: 扫描完成的 callback true: 成功 false: 失败 scan_done_cb_t 注意示例例 wifi_station_scan 的回调函数 请勿在 user_init 中调 用本接 口, 本接 口必须在系统初始化完成后, 并且 ESP8266 Station 接 口使能的情况下调 用 void scan_done_cb_t (void *arg, STATUS status) void *arg: 扫描获取到的 AP 信息指针, 以链表形式存储, 数据结构 struct bss_info STATUS status: 扫描结果 wifi_station_scan(&config, scan_done); static void ICACHE_FLASH_ATTR scan_done(void *arg, STATUS status) { if (status == OK) { struct bss_info *bss_link = (struct bss_info *)arg;... } } wifi_station_ap_number_set 设置 ESP8266 Station 最多可记录 几个 AP 的信息 ESP8266 Station 成功连 入 一个 AP 时, 可以保存 AP 的 SSID 和 password 记录 本设置如果与原设置不不同, 会更更新保存到 Flash 系统区 bool wifi_station_ap_number_set (uint8 ap_number) uint8 ap_number: 记录 AP 信息的最 大数 目 ( 最 大值为 5) true: 成功 false: 失败 wifi_station_get_ap_info 获取 ESP8266 Station 保存的 AP 信息, 最多记录 5 个 uint8 wifi_station_get_ap_info(struct station_config config[]) struct station_config config[]:ap 的信息, 数组 大 小必须为 5 Espressif 39! /! 153

56 示例例 记录 AP 的数 目 struct station_config config[5]; int i = wifi_station_get_ap_info(config); wifi_station_ap_change ESP8266 Station 切换到已记录的某号 AP 配置连接 bool wifi_station_ap_change (uint8 new_ap_id) uint8 new_ap_id:ap 记录的 ID 值, 从 0 开始计数 true: 成功 false: 失败 wifi_station_get_current_ap_id 获取当前连接的 AP 保存记录 ID 值 ESP8266 可记录每 一个配置连接的 AP, 从 0 开始计数 uint8 wifi_station_get_current_ap_id (); 当前连接的 AP 保存记录的 ID 值 wifi_station_get_auto_connect 查询 ESP8266 Station 上电是否会 自动连接已记录的 AP( 路路由 ) uint8 wifi_station_get_auto_connect(void) 0: 不不 自动连接 AP 非 0: 自动连接 AP wifi_station_set_auto_connect 注意 设置 ESP8266 Station 上电是否 自动连接已记录的 AP( 路路由 ), 默认为 自动连接 本接 口如果在 user_init 中调 用, 则当前这次上电就 生效 ; 如果在其他地 方调 用, 则下 一 次上电 生效 本设置如果与原设置不不同, 会更更新保存到 Flash 系统区 bool wifi_station_set_auto_connect(uint8 set) uint8 set: 上电是否 自动连接 AP 0: 不不 自动连接 AP 1: 自动连接 AP true: 成功 false: 失败 Espressif 40! /! 153

57 wifi_station_dhcpc_start 开启 ESP8266 Station DHCP client DHCP 默认开启 注意 DHCP 与静态 IP wifi_set_ip_info 互相影响, 以最后设置的为准 : DHCP 开启, 则静态 IP 失效 ; 设置静态 IP, 则关闭 DHCP bool wifi_station_dhcpc_start(void) true: 成功 false: 失败 wifi_station_dhcpc_stop 关闭 ESP8266 Station DHCP client DHCP 默认开启 注意 DHCP 与静态 IP wifi_set_ip_info 互相影响 : DHCP 开启, 则静态 IP 失效 ; 设置静态 IP, 则 DHCP 关闭 bool wifi_station_dhcpc_stop(void) true: 成功 false: 失败 wifi_station_dhcpc_status 查询 ESP8266 Station DHCP client 状态 enum dhcp_status wifi_station_dhcpc_status(void) enum dhcp_status { DHCP_STOPPED, DHCP_STARTED }; wifi_station_dhcpc_set_maxtry 设置 ESP8266 Station DHCP client 最 大重连次数 默认会 一直重连 bool wifi_station_dhcpc_set_maxtry(uint8 num) uint8 num: 最 大重连次数 true: 成功 false: 失败 Espressif 41! /! 153

58 wifi_station_set_reconnect_policy 注意 设置 ESP8266 Station 连接 AP 失败或断开后是否重连 默认重连 建议在 user_init 中调 用本接 口 bool wifi_station_set_reconnect_policy(bool set) bool set true: 断开则重连 false: 断开不不重连 true: 成功 false: 失败 wifi_station_get_rssi 关闭 ESP8266 Station 已连接的 AP 信号强度 sint8 wifi_station_get_rssi(void) <10: 查询成功, 信号强度 31: 查询失败, 错误码 wifi_station_set_hostname 设置 ESP8266 Station DHCP 分配的主机名称 bool wifi_station_set_hostname(char* hostname) char* hostname: 主机名称, 最 长 32 个字符 true: 成功 false: 失败 wifi_station_get_hostname 查询 ESP8266 Station DHCP 分配的主机名称 char* wifi_station_get_hostname(void) 主机名称 wifi_softap_get_config 查询 ESP8266 Wi-Fi SoftAP 接 口的当前配置 bool wifi_softap_get_config(struct softap_config *config) Espressif 42! /! 153

59 struct softap_config *config:esp8266 SoftAP 配置 true: 成功 false: 失败 wifi_softap_get_config_default 查询 ESP8266 Wi-Fi SoftAP 接 口保存在 Flash 中的配置 bool wifi_softap_get_config_default(struct softap_config *config) struct softap_config *config:esp8266 SoftAP 配置 true: 成功 false: 失败 wifi_softap_set_config 设置 Wi-Fi SoftAP 接 口配置, 并保存到 Flash 请在 ESP8266 SoftAP 使能的情况下, 调 用本接 口 注意 本设置如果与原设置不不同, 将更更新保存到 Flash 系统区 因为 ESP8266 只有 一个信道, 因此 SoftAP+Station 共存模式时,ESP8266 SoftAP 接 口会 自动调节信道与 ESP8266 Station 一致, 详细说明请参考附录 bool wifi_softap_set_config (struct softap_config *config) struct softap_config *config:esp8266 Wi-Fi SoftAP 配置 true: 成功 false: 失败 wifi_softap_set_config_current 设置 Wi-Fi SoftAP 接 口配置, 不不保存到 Flash 请在 ESP8266 SoftAP 使能的情况下, 调 用本接 口 注意 因为 ESP8266 只有 一个信道, 因此 SoftAP+Station 共存模式时,ESP8266 SoftAP 接 口会 自动调节信道与 ESP8266 Station 一致, 详细说明请参考附录 bool wifi_softap_set_config_current (struct softap_config *config) struct softap_config *config:esp8266 Wi-Fi SoftAP 配置 true: 成功 false: 失败 wifi_softap_get_station_num 获取 ESP8266 SoftAP 下连接的 Station 个数 Espressif 43! /! 153

60 uint8 wifi_softap_get_station_num(void) ESP8266 SoftAP 下连接的 Station 个数 wifi_softap_get_station_info 注意 获取 ESP8266 SoftAP 接 口下连 入的 Station 的信息, 包括 MAC 和 IP 本接 口基于 DHCP 实现, 因此不不 支持静态 IP 或者其他没有重新 DHCP 的情况 struct station_info * wifi_softap_get_station_info(void) struct station_info*:station 信息的结构体 wifi_softap_free_station_info 释放调 用 wifi_softap_get_station_info 时结构体 station_info 占 用的空间 void wifi_softap_free_station_info(void) wifi_softap_dhcps_start 示例例获取 MAC 和 IP 信息示例例, 注意释放资源 : 示例例 1 示例例 2 struct station_info * station = wifi_softap_get_station_info(); struct station_info * next_station; while(station) { os_printf(bssid : MACSTR, ip : IPSTR/n, MAC2STR(station->bssid), IP2STR(&station->ip)); next_station = STAILQ_NEXT(station, next); os_free(station); // Free it directly station = next_station; } struct station_info * station = wifi_softap_get_station_info(); while(station){ os_printf(bssid : MACSTR, ip : IPSTR/n, MAC2STR(station->bssid), IP2STR(&station->ip)); station = STAILQ_NEXT(station, next); } wifi_softap_free_station_info(); // Free it by calling functions 开启 ESP8266 SoftAP DHCP server DHCP 默认开启 注意 DHCP 与静态 IP wifi_set_ip_info 互相影响, 以最后设置的为准 : DHCP 开启, 则静态 IP 失效 ; 设置静态 IP, 则关闭 DHCP bool wifi_softap_dhcps_start(void) Espressif 44! /! 153

61 true: 成功 false: 失败 wifi_softap_dhcps_stop 关闭 ESP8266 SoftAP DHCP server 默认开启 DHCP bool wifi_softap_dhcps_stop(void) true: 成功 false: 失败 wifi_softap_set_dhcps_lease 设置 ESP8266 SoftAP DHCP server 分配 IP 地址的范围 设置的 IP 分配范围必须与 ESP8266 SoftAP IP 在同 一 网段 注意 本接 口必须在 ESP8266 SoftAP DHCP server 关闭 wifi_softap_dhcps_stop 的情况下设 置 本设置仅对下 一次使能的 DHCP server 生效 wifi_softap_dhcps_start, 如果 DHCP server 再次被关闭, 则需要重新调 用本接 口设置 IP 范围 ; 否则之后 DHCP server 重新使能, 会使 用默认的 IP 地址分配范围 bool wifi_softap_set_dhcps_lease(struct dhcps_lease *please) struct dhcps_lease { struct ip_addr start_ip; struct ip_addr end_ip; }; true: 成功 false: 失败 Espressif 45! /! 153

62 ! 3. 应 用程序接 口 (API) void dhcps_lease_test(void) { struct dhcps_lease dhcp_lease; const char* start_ip = ; const char* end_ip = ; dhcp_lease.start_ip.addr = ipaddr_addr(start_ip); dhcp_lease.end_ip.addr = ipaddr_addr(end_ip); wifi_softap_set_dhcps_lease(&dhcp_lease); } 或者 示例例 void dhcps_lease_test(void) { } struct dhcps_lease dhcp_lease; IP4_ADDR(&dhcp_lease.start_ip, 192, 168, 5, 100); IP4_ADDR(&dhcp_lease.end_ip, 192, 168, 5, 105); wifi_softap_set_dhcps_lease(&dhcp_lease); void user_init(void) { } struct ip_info info; wifi_set_opmode(stationap_mode); //Set softap + station mode wifi_softap_dhcps_stop(); IP4_ADDR(&info.ip, 192, 168, 5, 1); IP4_ADDR(&info.gw, 192, 168, 5, 1); IP4_ADDR(&info.netmask, 255, 255, 255, 0); wifi_set_ip_info(softap_if, &info); dhcps_lease_test(); wifi_softap_dhcps_start(); wifi_softap_get_dhcps_lease 注意 查询 ESP8266 SoftAP DHCP server 分配 IP 地址的范围本接 口仅 支持在 ESP8266 SoftAP DHCP server 使能的情况下查询 bool wifi_softap_get_dhcps_lease(struct dhcps_lease *please) true: 成功 false: 失败 wifi_softap_set_dhcps_lease_time 注意 设置 ESP8266 SoftAP DHCP server 的租约时间 默认为 120 分钟 本接 口仅 支持在 ESP8266 SoftAP DHCP server 使能的情况下查询 bool wifi_softap_set_dhcps_lease_time(uint32 minute) Espressif 46! /! 153

63 uint32 minute: 租约时间, 单位 : 分钟, 取值范围 :[1,2880] true: 成功 false: 失败 wifi_softap_get_dhcps_lease_time 注意 查询 ESP8266 SoftAP DHCP server 的租约时间 本接 口仅 支持在 ESP8266 SoftAP DHCP server 使能的情况下查询 uint32 wifi_softap_get_dhcps_lease_time(void) 租约时间, 单位 : 分钟 wifi_softap_reset_dhcps_lease_time 注意 复位 ESP8266 SoftAP DHCP server 的租约时间 恢复到 120 分钟 本接 口仅 支持在 ESP8266 SoftAP DHCP server 使能的情况下查询 bool wifi_softap_reset_dhcps_lease_time(void) true: 成功 false: 失败 wifi_softap_dhcps_status 获取 ESP8266 SoftAP DHCP server 状态 enum dhcp_status wifi_softap_dhcps_status(void) enum dhcp_status { DHCP_STOPPED, DHCP_STARTED }; wifi_softap_set_dhcps_offer_option 设置 ESP8266 SoftAP DHCP server 属性 enum dhcps_offer_option{ OFFER_START = 0x00, 结构体 OFFER_ROUTER = 0x01, OFFER_END }; bool wifi_softap_set_dhcps_offer_option(uint8 level, void* optarg) Espressif 47! /! 153

64 示例例 uint8 level:offer_router, 设置 router 信息 void* optarg:bit0, 0 禁 用 router 信息 ;bit0, 1 启 用 router 信息 ; 默认为 1 true: 成功 false: 失败 uint8 mode = 0; wifi_softap_set_dhcps_offer_option(offer_router, &mode); wifi_set_phy_mode 设置 ESP8266 物理理层模式 ( b/g/n) bool wifi_set_phy_mode(enum phy_mode mode) enum phy_mode mode : 物理层模式 enum phy_mode { PHY_MODE_11B = 1, PHY_MODE_11G = 2, PHY_MODE_11N = 3 }; true: 成功 false: 失败 wifi_get_phy_mode 查询 ESP8266 物理理层模式 ( b/g/n) enum phy_mode wifi_get_phy_mode(void) enum phy_mode{ PHY_MODE_11B = 1, PHY_MODE_11G = 2, PHY_MODE_11N = 3 }; wifi_get_ip_info 注意 查询 Wi-Fi Station 接 口或者 SoftAP 接 口的 IP 地址 在 user_init 中, 由于初始化尚未完成, 法通过本接 口查询到有效 IP 地址 bool wifi_get_ip_info( uint8 if_index, struct ip_info *info ) uint8 if_index: 获取 Station 或者 SoftAP 接 口的信息 #define STATION_IF 0x00 #define SOFTAP_IF 0x01 struct ip_info *info: 获取到的 IP 信息 Espressif 48! /! 153

65 true: 成功 false: 失败 wifi_set_ip_info 注意 设置 Wi-Fi Station 或者 SoftAP 的 IP 地址 本接 口设置静态 IP, 请先关闭对应 DHCP wifi_station_dhcpc_stop 或者 wifi_softap_dhcps_stop 设置静态 IP, 则关闭 DHCP;DHCP 开启, 则静态 IP 失效 bool wifi_set_ip_info( uint8 if_index, struct ip_info *info ) uint8 if_index: 设置 Station 或者 SoftAP 接 口 #define STATION_IF 0x00 #define SOFTAP_IF 0x01 struct ip_info *info: 获取到的 IP 信息 true: 成功 false: 失败 wifi_set_opmode(stationap_mode); //Set softap + station mode struct ip_info info; wifi_station_dhcpc_stop(); wifi_softap_dhcps_stop(); 示例例 IP4_ADDR(&info.ip, 192, 168, 3, 200); IP4_ADDR(&info.gw, 192, 168, 3, 1); IP4_ADDR(&info.netmask, 255, 255, 255, 0); wifi_set_ip_info(station_if, &info); IP4_ADDR(&info.ip, 10, 10, 10, 1); IP4_ADDR(&info.gw, 10, 10, 10, 1); IP4_ADDR(&info.netmask, 255, 255, 255, 0); wifi_set_ip_info(softap_if, &info); wifi_softap_dhcps_start(); wifi_set_macaddr 设置 MAC 地址 本接 口必须在 user_init 中调 用 注意 ESP8266 SoftAP 和 Station MAC 地址不不同, 请勿将两者设置为同 一 MAC 地址 ESP8266 MAC 地址第 一个字节的 bit 0 不不能为 1 例例如,MAC 地址可以设置为 1a:XX:XX:XX:XX:XX, 但不不能设置为 15:XX:XX:XX:XX:XX bool wifi_set_macaddr( uint8 if_index, uint8 *macaddr ) Espressif 49! /! 153

66 uint8 if_index: 设置 Station 或者 SoftAP 接 口 #define STATION_IF 0x00 #define SOFTAP_IF 0x01 uint8 *macaddr:mac 地址 true: 成功 false: 失败 wifi_set_opmode(stationap_mode); 示例例 char sofap_mac[6] = {0x16, 0x34, 0x56, 0x78, 0x90, 0xab}; char sta_mac[6] = {0x12, 0x34, 0x56, 0x78, 0x90, 0xab}; wifi_set_macaddr(softap_if, sofap_mac); wifi_set_macaddr(station_if, sta_mac); wifi_get_macaddr 查询 MAC 地址 bool wifi_get_macaddr( uint8 if_index, uint8 *macaddr ) uint8 if_index: 查询 Station 或者 SoftAP 接 口 #define STATION_IF 0x00 #define SOFTAP_IF 0x01 uint8 *macaddr:mac 地址 true: 成功 false: 失败 wifi_set_sleep_type 设置省电模式 设置为 NONE_SLEEP_T, 则关闭省电模式 默认为 Modem-sleep 模式 注意 Light Sleep 为了了降低功耗, 将 TCP timer tick 由原本的 250ms 改为了了 3s, 这将导致 TCP timer 超时时间相应增加 ; 如果 用户对 TCP timer 的准确度有要求, 请使 用 modem sleep 或者 deep sleep 模式 bool wifi_set_sleep_type(enum sleep_type type) enum sleep_type type: 省电模式 true: 成功 false: 失败 wifi_get_sleep_type 查询省电模式 enum sleep_type wifi_get_sleep_type(void) Espressif 50! /! 153

67 enum sleep_type { NONE_SLEEP_T = 0; LIGHT_SLEEP_T, MODEM_SLEEP_T }; wifi_status_led_install 注册 Wi-Fi 状态 LED void wifi_status_led_install ( uint8 gpio_id, uint32 gpio_name, uint8 gpio_func ) uint8 gpio_id:gpio ID uint8 gpio_name:gpio MUX 名称 uint8 gpio_func:gpio 示例例 使 用 GPIO0 作为 Wi-Fi 状态 LED #define HUMITURE_WIFI_LED_IO_MUX PERIPHS_IO_MUX_GPIO0_U #define HUMITURE_WIFI_LED_IO_NUM 0 #define HUMITURE_WIFI_LED_IO_FUNC FUNC_GPIO0 wifi_status_led_install(humiture_wifi_led_io_num, HUMITURE_WIFI_LED_IO_MUX, HUMITURE_WIFI_LED_IO_FUNC) wifi_status_led_uninstall 注销 Wi-Fi 状态 LED void wifi_status_led_uninstall () wifi_set_broadcast_if 注意 设置 ESP8266 发送 UDP 广播包时, 从 Station 接 口还是 SoftAP 接 口发送 默认从 SoftAP 接 口发送 如果设置仅从 Station 接 口发 UDP 广播包, 会影响 ESP8266 SoftAP 的,DHCP server 法使 用 需要使能 SoftAP 的 广播包, 才可正常使 用 ESP8266 SoftAP bool wifi_set_broadcast_if (uint8 interface) uint8 interface 1:station 2:SoftAP 3:Station 和 SoftAP 接 口均发送 Espressif 51! /! 153

68 true: 成功 false: 失败 wifi_get_broadcast_if 查询 ESP8266 发送 UDP 广播包时, 从 Station 接 口还是 SoftAP 接 口发送 uint8 wifi_get_broadcast_if (void) 1:Station 2:SoftAP 3:Station 和 SoftAP 接 口均发送 wifi_set_event_handler_cb 注册 Wi-Fi event 处理理回调 void wifi_set_event_handler_cb(wifi_event_handler_cb_t cb) wifi_event_handler_cb_t cb: 回调函数 Espressif 52! /! 153

69 示例例 void wifi_handle_event_cb(system_event_t *evt) { os_printf("event %x\n", evt->event); switch (evt->event) { case EVENT_STAMODE_CONNECTED: os_printf("connect to ssid %s, channel %d\n", evt->event_info.connected.ssid, evt->event_info.connected.channel); break; case EVENT_STAMODE_DISCONNECTED: os_printf("disconnect from ssid %s, reason %d\n", evt->event_info.disconnected.ssid, evt->event_info.disconnected.reason); break; case EVENT_STAMODE_AUTHMODE_CHANGE: os_printf("mode: %d -> %d\n", evt->event_info.auth_change.old_mode, evt->event_info.auth_change.new_mode); break; case EVENT_STAMODE_GOT_IP: os_printf("ip:" IPSTR ",mask:" IPSTR ",gw:" IPSTR, IP2STR(&evt->event_info.got_ip.ip), IP2STR(&evt->event_info.got_ip.mask), IP2STR(&evt->event_info.got_ip.gw)); os_printf("\n"); break; case EVENT_SOFTAPMODE_STACONNECTED: os_printf("station: " MACSTR "join, AID = %d\n", MAC2STR(evt->event_info.sta_connected.mac), evt->event_info.sta_connected.aid); break; case EVENT_SOFTAPMODE_STADISCONNECTED: os_printf("station: " MACSTR "leave, AID = %d\n", MAC2STR(evt->event_info.sta_disconnected.mac), evt->event_info.sta_disconnected.aid); break; default: break; } } void user_init(void) { // TODO: add your own code here... wifi_set_event_handler_cb(wifi_handle_event_cb); } wifi_wps_enable 注意 使能 Wi-Fi WPS WPS 必须在 ESP8266 Station 使能的情况下调 用 Espressif 53! /! 153

70 结构体 typedef enum wps_type { WPS_TYPE_DISABLE=0, WPS_TYPE_PBC, WPS_TYPE_PIN, WPS_TYPE_DISPLAY, WPS_TYPE_MAX, }WPS_TYPE_t; bool wifi_wps_enable(wps_type_t wps_type) WPS_TYPE_t wps_type:wps 的类型, 目前仅 支持 WPS_TYPE_PBC true: 成功 false: 失败 wifi_wps_disable 关闭 Wi-Fi WPS, 释放占 用的资源 bool wifi_wps_disable(void) true: 成功 false: 失败 wifi_wps_start 注意 WPS 开始进 行行交互 WPS 必须在 ESP8266 Station 使能的情况下调 用 bool wifi_wps_start(void) true: 成功开始交互, 并不不表示 WPS 成功完成 false: 失败 wifi_set_wps_cb 回调及 结构体 设置 WPS 回调函数, 回调函数中将传 入 WPS 运 行行状态 WPS 不不 支持 WEP 加密 方式 typedef void (*wps_st_cb_t)(int status); enum wps_cb_status { WPS_CB_ST_SUCCESS = 0, WPS_CB_ST_FAILED, WPS_CB_ST_TIMEOUT, WPS_CB_ST_WEP, // WPS failed because that WEP is not supported. WPS_CB_ST_SCAN_ERR, // can not find the target WPS AP }; Espressif 54! /! 153

71 如果回调函数的传 入状态为 WPS_CB_ST_SUCCESS, 表示成功获得 AP 密钥, 请调 用 注意 wifi_wps_disable 关闭 WPS 释放资源, 并调 用 wifi_station_connect 连接 AP 否则, 表示 WPS 失败, 可以创建 一个定时器器, 间隔 一段时间后调 用 wifi_wps_start 再次尝试 WPS, 或者调 用 wifi_wps_disable 关闭 WPS 并释放资源 bool wifi_set_wps_cb(wps_st_cb_t cb) wps_st_cb_t cb: 回调函数 true: 成功 false: 失败 wifi_register_send_pkt_freedom_cb 注册 freedom 发包的回调函数 freedom 发包, 即 支持发送 用户 自定义 的包 freedom 发包必须等前 一个包发送完毕, 进 入发包回调 freedom_outside_cb_t 之后, 才能发下 一个包 设置发送回调函数可以 用来判别包是否发送成功 (IEEE MAC 底层是否发送成功 ) 使 用发送回调函数请注意如下情况 : 针对单播包 : - 回调函数状态显示成功时, 对 方应 用层实际没有收到的状况 原因 : 1. 存在流氓设备进 行行攻击 注意 2. 加密密钥设置错误 3. 应 用层丢包 若需要更更强地发包保证发包成功率, 请在应 用层实现发包握 手机制 - 回调函数状态显示失败时, 对 方应 用层实际已收到的状况 原因 : 1. 信道繁忙, 未收到对 方ACK 请注意应 用层发包重传, 接收 方需要检测重传包 针对组播包 ( 包括 广播包 ): - 回调函数状态显示成功, 表示组播包已成功发送 回调 - 回调函数状态显示失败, 表示组播包发送失败 typedef void (*freedom_outside_cb_t)(uint8 status); status:0, 发包成功 ; 其他值, 发包失败 freedom_outside_cb_t cb: 回调函数 0: 注册成功 -1: 注册失败 wifi_unregister_send_pkt_freedom_cb 注销 freedom 发包的回调函数 void wifi_unregister_send_pkt_freedom_cb(void) Espressif 55! /! 153

72 wifi_send_pkt_freedom 发包函数 发送包必须是完整的 包, 长度不不包含 FCS 发包 长度必须 大于最 小 头, 即 24 字节, 且不不能超过 1400 字节, 否则发包失败 duration 域填写效, 由 ESP8266 底层程序决定, 自动填充 注意 发包速率限制成管理理包速率, 与系统的发包速率 一致 支持发送 : 非加密的数据包, 非加密的 beacon/probe req/probe resp 不不 支持发送 : 所有加密包 ( 即包头中的加密 bit 必须为 0, 否则发包失败 ), 控制包, 除 beacon/probe req/probe resp 以外的其他管理理包 freedom 发包必须等前 一个包发送完毕, 进 入发包回调之后, 才能发下 一个包 int wifi_send_pkt_freedom(uint8 *buf, int len,bool sys_seq) uint8 *buf: 数据包指针 int len: 数据包 长度 bool sys_seq: 是否跟随系统的 包 sequence number, 如果跟随系统, 将会在每次发包后 自加 1 0: 成功 -1: 失败 wifi_rfid_locp_recv_open 开启 RFID LOCP (Location Control Protocol), 用于接收 WDS 类型的包 int wifi_rfid_locp_recv_open(void) 0: 成功其他值 : 失败 wifi_rfid_locp_recv_close 关闭 RFID LOCP (Location Control Protocol) void wifi_rfid_locp_recv_close(void) Espressif 56! /! 153

73 wifi_register_rfid_locp_recv_cb 回调 注册 WDS 收包回调 仅在收到的 WDS 包的第 一个 MAC 地址为组播地址时, 才会进 入回调函数 typedef void (*rfid_locp_cb_t)(uint8 *frm, int len, int rssi); uint8 *frm: 指向 包头的指针 int len: 数据包 长度 int rssi: 信号强度 0: 成功其他值 : 失败 wifi_unregister_rfid_locp_recv_cb 注销 WDS 收包回调 void wifi_unregister_rfid_locp_recv_cb(void) wifi_enable_gpio_wakeup 注意 使能 GPIO 唤醒 Light-sleep 模式的 在 自动 Light-sleep 休眠 wifi_set_sleep_type(light_sleep_t); 的情况下, 由 GPIO 触发 ESP8266 从 Light-sleep 唤醒之后, 如需再次进 入休眠时, 将判断唤醒 GPIO 的状态 : 如果 GPIO 仍然处于唤醒状态, 则进 入 Modem-sleep 休眠 ; 如果 GPIO 不不处于唤醒状态, 则进 入 Light-sleep 休眠 void wifi_enable_gpio_wakeup(uint32 i, GPIO_INT_TYPE intr_status) uint32 i:gpio 号, 取值范围 :[0, 15] GPIO_INT_TYPE intr_status:gpio 触发唤醒的状态 设置 GPIO12 低电平时, 将 ESP8266 从 Light-sleep 模式唤醒 示例例 GPIO_DIS_OUTPUT(12); PIN_FUNC_SELECT(PERIPHS_IO_MUX_MTDI_U, FUNC_GPIO12); wifi_enable_gpio_wakeup(12, GPIO_PIN_INTR_LOLEVEL); wifi_disable_gpio_wakeup 取消 GPIO 唤醒 Light-sleep 模式的 Espressif 57! /! 153

74 void wifi_disable_gpio_wakeup(void) wifi_set_country 设置 WiFi 国家码 bool wifi_set_country(wifi_country_t *country) wifi_country_t *country: 国家码信息 默认国家码为 {.cc="cn",.schan=1,.nchan=13, policy=wifi_country_policy_auto} 当 policy=wifi_country_policy_auto,esp8266 的国家码会在连上 AP 后, 自动更更改 为与 AP 一致 ; 当与 AP 断开连接后, 又回到原设置值 注意 当 policy=wifi_country_policy_manual,esp8266 的国家码将始终保持为设置值 在 station+softap 模式下, 如果 ESP8266 station 的国家码信息改变,softAP 端 probe response/beacon 中的 country IE 国家码信息也会同样改变 国家码信息不不保存在 flash, 重新上电后, 需要重新配置 true: 成功 false: 失败 wifi_get_country 获取当前 WiFi 国家码 bool wifi_get_country(wifi_country_t *country) wifi_country_t *country: 国家码信息 true: 成功 false: 失败 wifi_set_sleep_level 设置 modem sleep 和 light sleep 的 sleep level bool wifi_set_sleep_level(enum sleep_level level) level: modem sleep 和 light sleep 的 sleep level true: 成功 false: 失败 Espressif 58! /! 153

75 如需设置, 请在 wifi_set_sleep_type 调 用本接 口 modem sleep 和 light sleep 支持两种 sleep level: 说明 - 最 小 sleep level:esp station 在每个 DTIM 都会醒来接收 beacon; 广播数据会在 DTIM 之后传输, 因此不不会丢失 ; 但如果 AP 的 DTIM 设置较短, 则此配置法达到较好的低功耗效果 - 最 大 sleep level:esp station 在每个 listen interval 都会醒来接收 beacon; 这样在 DTIM 时 ESP station 可能在休眠中, 广播数据会因此丢失 ; 如果将 listen interval 设置的越 长, 低功耗效果越好, 但也会因此丢失更更多的 广播数据 - 默认为最 小 sleep level - listen interval 可以通过 API wifi_set_listen_interval 设置 wifi_get_sleep_level 查询 modem sleep 和 light sleep 的 sleep level enum sleep_level wifi_get_sleep_level(void) sleep level 值 wifi_set_listen_interval 说明 设置 modem sleep 和 light sleep 最 大 sleep level 下的 listen interval bool wifi_set_listen_interval(uint8 interval) interval: modem sleep 和 light sleep 最 大 sleep level 下的侦听间隔, 单位是 AP 的 一个 beacon interval, 取值范围 : [1, 10] true: 成功 false: 失败 本设置仅针对 modem sleep 和 light sleep 的最 大 sleep level(max_sleep_t) 如需设置, 应按照以下顺序调 用 : - wifi_set_sleep_level(max_sleep_t) - wifi_set_listen_interval - wifi_set_sleep_type wifi_get_listen_interval 查询 modem sleep 和 light sleep 最 大 sleep level 下的 listen interval uint8 wifi_get_listen_interval(void) Espressif 59! /! 153

76 modem sleep 和 light sleep 最 大 sleep level 下的侦听间隔 Espressif 60! /! 153

77 3.6. Rate Control 接 口 Wi-Fi Rate Control 接 口位于 /ESP8266_NONOS_SDK/include/user_interface.h wifi_set_user_fixed_rate 设置 ESP8266 Station 或 SoftAP 发数据的固定 rate 和 mask enum FIXED_RATE { 定义 注意 } PHY_RATE_48 = 0x8, PHY_RATE_24 = 0x9, PHY_RATE_12 = 0xA, PHY_RATE_6 = 0xB, PHY_RATE_54 = 0xC, PHY_RATE_36 = 0xD, PHY_RATE_18 = 0xE, PHY_RATE_9 = 0xF, #define FIXED_RATE_MASK_NONE #define FIXED_RATE_MASK_STA #define FIXED_RATE_MASK_AP #define FIXED_RATE_MASK_ALL (0x01) (0x02) (0x03) (0x00) 当 enable_mask 的对应 bit 为 1,ESP8266 Station 或 SoftAP 才会以固定 rate 发送数据 如果 enable_mask 设置成 0, 则 ESP8266 Station 和 SoftAP 均不不会以固定 rate 发送数据 ESP8266 Station 和 SoftAP 共享同 一个 rate, 不不 支持分别设置为不不同 rate 值 int wifi_set_user_fixed_rate(uint8 enable_mask, uint8 rate) uint8 enable_mask - 0x00: 禁 用固定 rate - 0x01: 固定 rate 用于 ESP8266 Station 接 口 - 0x02: 固定 rate 用于 ESP8266 SoftAP 接 口 - 0x03: 固定 rate 用于 ESP8266 Station+SoftAP uint8 rate: 固定 rate 值 0: 成功其他 : 失败 wifi_get_user_fixed_rate 获取已经设置的固定 rate 的 mask 和 rate 值 int wifi_get_user_fixed_rate(uint8 *enable_mask, uint8 *rate) uint8 *enable_mask:mask 的指针 uint8 *rate:rate 的指针 0: 成功其他 : 失败 Espressif 61! /! 153

78 wifi_set_user_sup_rate 设置 ESP8266 beacon probe req/resp 等包 里里的 support rate 的 IE 中 支持的 rate 范围 用于 将 ESP8266 支持的通信速率告知通信对 方, 以限制对 方设备的发包速率 注意本接 口 目前仅 支持 g 模式, 后续会增加 支持 b 定义示例例 enum support_rate { RATE_11B5M = 0, RATE_11B11M = 1, RATE_11B1M = 2, RATE_11B2M = 3, RATE_11G6M = 4, RATE_11G12M = 5, RATE_11G24M = 6, RATE_11G48M = 7, RATE_11G54M = 8, RATE_11G9M = 9, RATE_11G18M = 10, RATE_11G36M = 11, }; int wifi_set_user_sup_rate(uint8 min, uint8 max) uint8 min:support rate 下限值, 仅 支持从 enum support_rate 中取值 uint8 max:support rate 上限值, 仅 支持从 enum support_rate 中取值 0: 成功 其他 : 失败 wifi_set_user_sup_rate(rate_11g6m, RATE_11G24M); Espressif 62! /! 153

79 wifi_set_user_rate_limit 设置 ESP8266 发包的初始速率范围 重传速率则不不受此接 口限制 enum RATE_11B_ID { RATE_11B_B11M = 0, RATE_11B_B5M = 1, RATE_11B_B2M = 2, RATE_11B_B1M = 3, } 定义 enum RATE_11G_ID { RATE_11G_G54M = 0, RATE_11G_G48M = 1, RATE_11G_G36M = 2, RATE_11G_G24M = 3, RATE_11G_G18M = 4, RATE_11G_G12M = 5, RATE_11G_G9M = 6, RATE_11G_G6M = 7 RATE_11G_B5M = 8, RATE_11G_B2M = 9, RATE_11G_B1M = 10 } enum RATE_11N_ID { RATE_11N_MCS7S = 0, RATE_11N_MCS7 = 1, RATE_11N_MCS6 = 2, RATE_11N_MCS5 = 3, RATE_11N_MCS4 = 4, RATE_11N_MCS3 = 5, RATE_11N_MCS2 = 6, RATE_11N_MCS1 = 7, RATE_11N_MCS0 = 8, RATE_11N_B5M = 9, RATE_11N_B2M = 10, RATE_11N_B1M = 11 } bool wifi_set_user_rate_limit(uint8 mode, uint8 ifidx, uint8 max, uint8 min) uint8 mode: 设置模式 #define RC_LIMIT_11B 0 #define RC_LIMIT_11G 1 #define RC_LIMIT_11N 2 uint8 ifidx: 设置接 口 0x00 - ESP8266 station 接口 0x01 - ESP8266 soft-ap 接口 uint8 max: 速率上限 请从第 一个 mode 对应的速率枚举中取值 示例例 uint8 min: 速率下限 请从第 一个 mode 对应的速率枚举中取值 true: 成功 false: 失败设置 11G 模式下的 ESP8266 station 接 口的速率, 限制为最 大 18M, 最 小 6M wifi_set_user_rate_limit(rc_limit_11g, 0, RATE_11G_G18M, RATE_11G_G6M); Espressif 63! /! 153

80 wifi_set_user_limit_rate_mask 定义 设置使能受 wifi_set_user_rate_limit 限制速率的接 口 #define LIMIT_RATE_MASK_NONE (0x00) #define LIMIT_RATE_MASK_STA (0x01) #define LIMIT_RATE_MASK_AP (0x02) #define LIMIT_RATE_MASK_ALL (0x03) bool wifi_ set_user_limit_rate_mask(uint8 enable_mask) uint8 enable_mask 0x00:ESP8266 Station+SoftAP 接 口均不不受限制 0x01:ESP8266 Station 接 口开启限制 0x02:ESP8266 SoftAP 接 口开启限制 0x03:ESP8266 Station+SoftAP 接 口均开启限制 true: 成功 false: 失败 wifi_get_user_limit_rate_mask 查询当前受 wifi_set_user_rate_limit 限制速率的接 口 uint8 wifi_get_user_limit_rate_mask(void) 0x00:ESP8266 Station+SoftAP 接 口均不不受限制 0x01:ESP8266 Station 接 口开启限制 0x02:ESP8266 SoftAP 接 口开启限制 0x03:ESP8266 Station+SoftAP 接 口均开启限制 Espressif 64! /! 153

81 3.7. 强制休眠接 口 强制休眠接 口位于 /ESP8266_NONOS_SDK/include/user_interface.h 使 用强制休眠, 必须先设置 Wi-Fi 工作模式为 NULL_MODE 从强制休眠中唤醒 ESP8266, 或者休眠时间到, 进 入唤醒回调 ( 由 wifi_fpm_set_wakeup_cb 注册 ) 后, 先关闭强制休眠, 才能再设置 Wi-Fi 工作模式为 Station SoftAP 或 Station+SoftAP 的正常 工作模式运 行行, 具体可参考本章节后 文提供的 示例例代码 注意, 定时器器会影响进 入 Light-sleep 模式, 如需 Light-sleep 休眠, 请先将定时器器关闭 Light Sleep 为了了降低功耗, 将 TCP timer tick 由原本的 250ms 改为了了 3s, 这将导致 TCP timer 超时时间相应增加 ; 如果 用户对 TCP timer 的准确度有要求, 请使 用 modem sleep 或者 deep sleep 模式 wifi_fpm_open 默认值 开启强制休眠 void wifi_fpm_open (void) 强制 sleep 关闭 wifi_fpm_close 关闭强制休眠 void wifi_fpm_close (void) wifi_fpm_do_wakeup 注意 唤醒 MODEM_SLEEP_T 类型的强制休眠本接 口仅 支持在强制休眠开启的情况下调 用, 可在 wifi_fpm_open 之后调 用 ; 在 wifi_fpm_close 之后, 不不可以调 用 void wifi_fpm_do_wakeup (void) Espressif 65! /! 153

82 wifi_fpm_set_wakeup_cb 设置强制休眠的定时唤醒超时, 系统醒来后的回调函数 本接 口仅 支持在强制休眠开启的情况下调 用, 可在 wifi_fpm_open 之后调 用 ; 在 wifi_fpm_close 之后, 不不可以调 用 注意 仅在定时唤醒 wifi_fpm_do_sleep 且不不为 0xFFFFFFF 的定时时间到, 系统醒来, 才会进 入唤醒回调 fpm_wakeup_cb_func MODEM_SLEEP_T 类型的强制休眠被 wifi_fpm_do_wakeup 唤醒, 并不不会进 入唤醒回调 void wifi_fpm_set_wakeup_cb(void (*fpm_wakeup_cb_func)(void)) void (*fpm_wakeup_cb_func)(void): 回调函数 wifi_fpm_do_sleep 注意 让系统强制休眠, 休眠时间到后, 系统将 自动醒来 本接 口仅 支持在强制休眠开启的情况下调 用, 可在 wifi_fpm_open 之后调 用 ; 在 wifi_fpm_close 之后, 不不可以调 用 本接 口 0 表示休眠设置成功, 但并不不表示 立即进 入休眠状态 系统会在进 入底层相关任务处理理时, 进 行行休眠 请勿在调 用本接 口后, 立即调 用其他 Wi-Fi 相关操作 int8 wifi_fpm_do_sleep (uint32 sleep_time_in_us) uint32 sleep_time_in_us: 休眠时间, 单位 :us, 取值范围 :10000 ~ (0xFFFFFFF) 如果设置为 0xFFFFFFF, 则系统将 一直休眠, 直 至 : 若 wifi_fpm_set_sleep_type 设置为 LIGHT_SLEEP_T, 可被 GPIO 唤醒 若 wifi_fpm_set_sleep_type 设置为 MODEM_SLEEP_T, 可被 wifi_fpm_do_wakeup 唤醒 0: 休眠设置成功 -1: 强制休眠的状态错误, 休眠失败 wifi_fpm_set_sleep_type -2: 强制休眠未开启, 休眠失败 注意 设置系统强制休眠的休眠类型 如需调 用本接 口, 请在 wifi_fpm_open 之前调 用 void wifi_fpm_set_sleep_type (enum sleep_type type) Espressif 66! /! 153

83 }; enum sleep_type{ NONE_SLEEP_T = 0, LIGHT_SLEEP_T, MODEM_SLEEP_T, wifi_fpm_get_sleep_type 查询系统强制休眠的休眠类型 enum sleep_type wifi_fpm_get_sleep_type (void) enum sleep_type{ NONE_SLEEP_T = 0, LIGHT_SLEEP_T, MODEM_SLEEP_T, }; wifi_fpm_auto_sleep_set_in_null_mode 设置在关闭 Wi-Fi 模式 wifi_set_opmode(null_mode) 的情况下, 是否 自动进 入 Modem-sleep 模式 void wifi_fpm_auto_sleep_set_in_null_mode (uint8 req) uint8 req 0: 关闭 Wi-Fi 模式后, 不不 自动进 入 Modem-sleep 模式 1: 关闭 Wi-Fi 模式后, 自动进 入 Modem-sleep 模式 示例例代码 调 用强制休眠接 口, 在需要的情况下强制关闭 RF 电路路以降低功耗 注意 : 强制休眠接 口调 用后, 并不不会 立即休眠, 而是等到系统 idle task 执 行行时才进 入休眠 请参考下述示例例使 用 示例例 一 :Modem-sleep 模式 强制进 入 Modem-sleep 模式, 即强制关闭 RF Espressif 67! /! 153

84 #define FPM_SLEEP_MAX_TIME 0xFFFFFFF void fpm_wakup_cb_func1(void) { wifi_fpm_close(); // disable force sleep function wifi_set_opmode(station_mode); // set station mode wifi_station_connect(); // connect to AP } void user_func(...) { wifi_station_disconnect(); wifi_set_opmode(null_mode); // set WiFi mode to null mode. wifi_fpm_set_sleep_type(modem_sleep_t); // modem sleep wifi_fpm_open(); // enable force sleep #ifdef SLEEP_MAX /* For modem sleep, FPM_SLEEP_MAX_TIME can only be wakened by calling wifi_fpm_do_wakeup. */ wifi_fpm_do_sleep(fpm_sleep_max_time); #else // wakeup automatically when timeout. wifi_fpm_set_wakeup_cb(fpm_wakup_cb_func1); // Set wakeup callback wifi_fpm_do_sleep(50*1000); #endif } #ifdef SLEEP_MAX void func1(void) { wifi_fpm_do_wakeup(); wifi_fpm_close(); wifi_set_opmode(station_mode); wifi_station_connect(); } #endif // disable force sleep function // set station mode // connect to AP 示例例 二 :Light-sleep 模式 强制进 入 Light-sleep 模式, 即强制关闭 RF 和 CPU, 需要设置 一个回调函数, 以便便唤醒 后程序继续运 行行 注意, 定时器器会影响进 入 Light-sleep 模式, 如需休眠, 请先将定时器器 关闭 #define FPM_SLEEP_MAX_TIME 0xFFFFFFF void fpm_wakup_cb_func1(void) { wifi_fpm_close(); // disable force sleep function wifi_set_opmode(station_mode); // set station mode wifi_station_connect(); // connect to AP } Espressif 68! /! 153

85 ! 3. 应 用程序接 口 (API) #ifndef SLEEP_MAX // Wakeup till time out. void user_func(...) { wifi_station_disconnect(); wifi_set_opmode(null_mode); // set WiFi mode to null mode. wifi_fpm_set_sleep_type(light_sleep_t); // light sleep wifi_fpm_open(); // enable force sleep wifi_fpm_set_wakeup_cb(fpm_wakup_cb_func1); // Set wakeup callback wifi_fpm_do_sleep(50*1000); } #else // Or wake up by GPIO void user_func(...) { wifi_station_disconnect(); wifi_set_opmode(null_mode); // set WiFi mode to null mode. wifi_fpm_set_sleep_type(light_sleep_t); // light sleep wifi_fpm_open(); // enable force sleep PIN_FUNC_SELECT(PERIPHS_IO_MUX_MTDI_U, FUNC_GPIO12); wifi_enable_gpio_wakeup(12, GPIO_PIN_INTR_LOLEVEL); wifi_fpm_set_wakeup_cb(fpm_wakup_cb_func1); // Set wakeup callback wifi_fpm_do_sleep(fpm_sleep_max_time);... } #endif Espressif 69! /! 153

86 3.8. ESP-NOW 接 口 结构体 esp_now_init ESP-NOW 接 口位于 /ESP8266_NONOS_SDK/include/espnow.h ESP-NOW 详细介绍请参考 文档 ESP-NOW 用户指南, 软件接 口使 用时的注意事项如下 : ESP-NOW 目前不不 支持组播包 ; ESP8266_NONOS_SDK_V2.1 及之后版本,ESP-NOW 支持发送 广播包, 但请注 意, 仅 支持不不加密的 广播包 ; 建议 slave 和 combo 角 色对应 ESP8266 SoftAP 模式或者 SoftAP+Station 共存模 式 ;controller 角 色对应 Station 模式 ; 当 ESP8266 处于 SoftAP+Station 共存模式时, 若作为 slave 或 combo 角 色, 将从 SoftAP 接 口通信 ; 若作为 controller 角 色, 将从 Station 接 口通信 ; ESP-NOW 不不实现休眠唤醒, 因此如果通信对 方的 ESP8266 Station 正处于休 眠状态,ESP-NOW 发包将会失败 ; ESP8266 Station 模式下, 最多可设置 10 个加密的 ESP-NOW peer, 加上不不加密的 设备, 总数不不超过 20 个 ; ESP8266 SoftAP 模式或者 SoftAP+station 模式下, 最多设置 6 个加密的 ESP-NOW peer, 加上不不加密的设备, 总数不不超过 20 个 enum esp_now_role { ESP_NOW_ROLE_IDLE = 0, ESP_NOW_ROLE_CONTROLLER, ESP_NOW_ROLE_SLAVE, ESP_NOW_ROLE_COMBO, // both slave and controller ESP_NOW_ROLE_MAX, }; 初始化 ESP-NOW init esp_now_init(void) 0: 成功其它 : 失败 Espressif 70! /! 153

87 esp_now_deinit 卸载 ESP-NOW int esp_now_deinit(void) 0: 成功其它 : 失败 esp_now_register_recv_cb 注册 ESP-NOW 收包的回调函数 当收到 ESP-NOW 的数据包, 进 入收包回调函数 typedef void (*esp_now_recv_cb_t)(u8 *mac_addr, u8 *data, u8 len) 注意 回调函数的 3 个分别为 : u8 *mac_add: 发包 方的 MAC 地址 u8 *data: 收到的数据 u8 len: 数据 长度 int esp_now_register_recv_cb(esp_now_recv_cb_t cb) esp_now_recv_cb_t cb: 回调函数 0: 成功其它 : 失败 esp_now_unregister_recv_cb 注销 ESP-NOW 收包的回调函数 int esp_now_unregister_recv_cb(void) 0: 成功其它 : 失败 Espressif 71! /! 153

88 esp_now_register_send_cb 设置 ESP-NOW 发包回调函数 当发送了了 ESP-NOW 的数据包, 进 入收包回调函数 void esp_now_send_cb_t(u8 *mac_addr, u8 status) 回调函数的 2 个分别为 : - u8 *mac_addr: 发包对 方的 目标 MAC 地址 - u8 status: 发包状态 ;0, 成功 ; 否则, 失败 对应结构体 : mt_tx_status { MT_TX_STATUS_OK = 0, MT_TX_STATUS_FAILED, } 发包回调函数不不判断密钥是否匹配, 如果使 用密钥加密, 请 自 行行确保密钥正确 设置发送回调函数可以 用来判别包是否发送成功 (IEEE MAC 底层是否发送成功 ) 使 用发送回调函数请注意如下情况 : 注意 针对单播包 : - 回调函数状态显示成功时, 对 方应 用层实际没有收到的状况 原因 : 1. 存在流氓设备进 行行攻击 2. 加密密钥设置错误 3. 应 用层丢包若需要更更强地发包保证发包成功率, 请在应 用层实现发包握 手机制 - 回调函数状态显示失败时, 对 方应 用层实际已收到的状况 原因 : 1. 信道繁忙, 未收到对 方ACK 请注意应 用层发包重传, 接收 方需要检测重传包 针对组播包 ( 包括 广播包 ): - 回调函数状态显示成功, 表示组播包已成功发送 - 回调函数状态显示失败, 表示组播包发送失败 u8 esp_now_register_send_cb(esp_now_send_cb_t cb) esp_now_send_cb_t cb: 回调函数 0: 成功其它 : 失败 esp_now_unregister_send_cb 注销 ESP-NOW 发包的回调函数, 不不再报告发包状态 int esp_now_unregister_send_cb(void) 0: 成功其它 : 失败 Espressif 72! /! 153

89 esp_now_send 发送 ESP-NOW 数据包 int esp_now_send(u8 *da, u8 *data, int len) u8 *da: 目的 MAC 地址 ; 如果为 NULL, 则遍历 ESP-NOW 维护的所有 MAC 地址进 行行发送, 否则, 向指定 MAC 地址发送 u8 *data: 要发送的数据 int len: 数据 长度 0: 成功其它 : 失败 esp_now_add_peer 增加 ESP-NOW 匹配设备, 将设备 MAC 地址存 入 ESP-NOW 维护的列列表 int esp_now_add_peer(u8 *mac_addr, u8 role,u8 channel, u8 *key, u8 key_len) u8 *mac_addr: 匹配设备的 MAC 地址 u8 channel: 匹配设备的信道值 u8 *key: 与该匹配设备通信时, 需使 用的密钥, 目前仅 支持 16 字节的密钥 u8 key_len: 密钥 长度, 目前 长度仅 支持 16 字节 0: 成功其它 : 失败 esp_now_del_peer 删除 ESP-NOW 匹配设备, 将设备 MAC 地址从 ESP-NOW 维护的列列表中删除 int esp_now_del_peer(u8 *mac_addr) u8 *mac_addr: 要删除设备的 MAC 地址 0: 成功其它 : 失败 esp_now_set_self_role 设置 自身 ESP-NOW 的 角 色 int esp_now_set_self_role(u8 role) u8 role: 角 色类型, 详 见 esp_now_role 0: 成功其它 : 失败 Espressif 73! /! 153

90 esp_now_get_self_role 查询 自身 ESP-NOW 的 角 色 u8 esp_now_get_self_role(void) 角 色类型 esp_now_set_peer_role 设置指定匹配设备的 ESP-NOW 角 色 如果重复设置, 新设置会覆盖原有设置 int esp_now_set_peer_role(u8 *mac_addr,u8 role) u8 *mac_addr: 指定设备的 MAC 地址 u8 role: 角 色类型, 详 见 esp_now_role 0: 成功其它 : 失败 esp_now_get_peer_role 查询指定匹配设备的 ESP-NOW 角 色 int esp_now_get_peer_role(u8 *mac_addr) u8 *mac_addr: 指定设备的 MAC 地址 角 色类型, 详 见 esp_now_role 否则, 失败 esp_now_set_peer_key 设置指定匹配设备的 ESP-NOW 密钥 如果重复设置, 新设置会覆盖原有设置 int esp_now_set_peer_key(u8 *mac_addr,u8 *key,u8 key_len) u8 *mac_addr: 指定设备的 MAC 地址 u8 *key: 密钥指针, 目前仅 支持 16 字节的密钥 ; 如果传 NULL, 则清除当前密钥 u8 key_len: 密钥 长度, 目前 长度仅 支持 16 字节 0: 成功其它 : 失败 Espressif 74! /! 153

91 esp_now_get_peer_key 查询指定匹配设备的 ESP-NOW 密钥 int esp_now_set_peer_key(u8 *mac_addr,u8 *key,u8 *key_len) u8 *mac_addr: 指定设备的 MAC 地址 u8 *key: 查询到的密钥指针, 请使 用 16 字节的 buffer 保存密钥 u8 key_len: 查询到的密钥 长度 0: 成功 >0: 找到 目标设备, 但未获得 key <0: 失败 esp_now_set_peer_channel 记录指定匹配设备的信道值 当与该指定设备进 行行 ESP-NOW 通信时, 先调 用 esp_now_get_peer_channel 查询该设备所在信道 ; 再调 用 wifi_set_channel 与该设备切换到同 一信道进 行行通信 ; 通信完成后, 请注意切换回原所在信道 int esp_now_set_peer_channel(u8 *mac_addr,u8 channel) u8 *mac_addr: 指定设备的 MAC 地址 u8 channel: 信道值, 一般为 1 ~ 13, 部分地区可能 用到 14 0: 成功其它 : 失败 esp_now_get_peer_channel 查询指定匹配设备的信道值 ESP-NOW 要求切换到同 一信道进 行行通信 int esp_now_get_peer_channel(u8 *mac_addr) u8 *mac_addr: 指定设备的 MAC 地址 1 ~ 13( 部分地区可能到 14), 成功否则, 失败 esp_now_is_peer_exist 根据 MAC 地址判断设备是否存在 int esp_now_is_peer_exist(u8 *mac_addr) u8 *mac_addr: 指定设备的 MAC 地址 Espressif 75! /! 153

92 0: 设备不不存在 >0: 出错, 查询失败 <0: 设备存在 esp_now_fetch_peer 注意 查询当前指向的 ESP-NOW 配对设备的 MAC 地址, 并将内部游标指向 ESP-NOW 维护列列表的后 一个设备或重新指向 ESP-NOW 维护列列表的第 一个设备 本接 口不不可重 入 第 一次调 用本接 口时, 必须为 true, 让内部游标指向 ESP-NOW 维护列列表的第 一个设备 u8 *esp_now_fetch_peer(bool restart) bool restart true: 将内部游标重新指向 ESP-NOW 维护列列表的第 一个设备 false: 将内部游标指向 ESP-NOW 维护列列表的后 一个设备 NULL: 不不存在已关联的 ESP-NOW 设备 否则, 当前指向的 ESP-NOW 配对设备的 MAC 地址指针 esp_now_get_cnt_info 查询已经匹配的全部设备总数和加密的设备总数 int esp_now_get_cnt_info(u8 *all_cnt, u8 *encryp_cnt) u8 *all_cnt: 已经匹配的全部设备总数 u8 *encryp_cnt: 加密的设备总数 0: 成功其它 : 失败 esp_now_set_kok 设置 用于将通信密钥加密的主密钥 (key of key) 所有设备的通信均共享同 一主密钥, 如不不设 置, 则使 用默认主密钥给通信密钥加密 如需调 用本接 口, 请在 esp_now_add_peer 和 esp_now_set_peer_key 接 口之前调 用 int esp_now_set_kok(u8 *key, u8 len) u8 *key: 主密钥指针 u8 len: 主密钥 长度, 目前 长度仅 支持 16 字节 0: 成功其它 : 失败 Espressif 76! /! 153

93 3.9. Simple-Pair 接 口 结构体 Simple-Pair 接 口位于 /ESP8266_NONOS_SDK/include/simple_pair.h 中 typedef enum { SP_ST_STA_FINISH = 0, SP_ST_AP_FINISH = 0, SP_ST_AP_RECV_NEG, SP_ST_STA_AP_REFUSE_NEG, // station 端协商结束 // AP 端协商结束 /* definitions below are error codes */ SP_ST_WAIT_TIMEOUT, SP_ST_SEND_ERROR, // AP 收到 station 发来的协商请求 // station 收到 AP 发来的协商拒绝 // 错误 : 协商过程超时 // 错误 : 发送数据出错 SP_ST_KEY_INSTALL_ERR, // 错误 : 密钥安装错误 SP_ST_KEY_OVERLAP_ERR, // 错误 : 同一个 MAC 地址有多个密钥 SP_ST_OP_ERROR, SP_ST_UNKNOWN_ERROR, SP_ST_MAX, } SP_ST_t; register_simple_pair_status_cb // 错误 : 操作错误 // 错误 : 未知错误 回调 注册 Simple-Pair 的状态回调函数 int register_simple_pair_status_cb(simple_pair_status_cb_t cb) typedef void (*simple_pair_status_cb_t)(u8 *sa, u8 status); u8 *sa: 对 方设备的源 MAC 地址 u8 status: 状态枚举值, 详 见 SP_ST_t 定义 simple_pair_status_cb_t cb: 状态回调函数 0: 成功其它 : 失败 unregister_simple_pair_status_cb 注销 Simple-Pair 的状态回调函数 void unregister_simple_pair_status_cb(void) Espressif 77! /! 153

94 simple_pair_init 初始化 Simple-Pair int simple_pair_init(void) 0: 成功其它 : 失败 simple_pair_deinit 反初始化 Simple-Pair void simple_pair_deinit(void) simple_pair_state_reset 重置 Simple-Pair 状态 当需要重新启动 Simple-Pair 时, 可调 用本接 口重置状态 int simple_pair_state_reset(void) 0: 成功其它 : 失败 simple_pair_ap_enter_announce_mode Simple-Pair 的 AP 端进 入 announce 模式 int simple_pair_ap_enter_announce_mode(void) 0: 成功其它 : 失败 simple_pair_sta_enter_scan_mode Simple-Pair 的 Station 端进 入 scan 模式 int simple_pair_sta_enter_scan_mode(void) 0: 成功其它 : 失败 Espressif 78! /! 153

95 simple_pair_sta_start_negotiate Simple-Pair 的 Station 端开始协商 int simple_pair_sta_start_negotiate(void) 0: 成功其它 : 失败 simple_pair_ap_start_negotiate Simple-Pair 的 AP 端同意协商 int simple_pair_ap_start_negotiate(void) 0: 成功其它 : 失败 simple_pair_ap_refuse_negotiate Simple-Pair 的 AP 端拒绝协商 int simple_pair_ap_refuse_negotiate(void) 0: 成功其它 : 失败 simple_pair_set_peer_ref 设置需要协商的设备的 仅向系统设置信息, 不不会安装 Key 或进 行行其他动作 若作为 Station 端, 则需要在 simple_pair_sta_start_negotiate 之前设置 若作为 AP 端, 则需要在 simple_pair_ap_start_negotiate 或者 simple_pair_ap_refuse_negotiate 之前设置 int simple_pair_set_peer_ref(u8 *peer_mac, u8 *tmp_key, u8 *ex_key) u8 *peer_mac: 需要协商的对端设备的 MAC 地址, 长度为 6 字节 不不能为 NULL u8 *tmp_key: 用于加密 Simple-Pair 通信的临时密钥, 长度为 16 字节 不不能为 NULL u8 *ex_key: 需要交换的 Key, 长度为 16 字节 如果为 NULL, 则系统默认使 用全 0 为 Key 0: 成功其它 : 失败 Espressif 79! /! 153

96 simple_pair_get_peer_ref 获取设置的值 需获取的, 传 入 NULL 即可 int simple_pair_get_peer_ref(u8 *peer_mac, u8 *tmp_key, u8 *ex_key) u8 *peer_mac: 需要协商的设备 MAC 地址, 长度为 6 字节 u8 *tmp_key: 用于加密 Simple-Pair 通信的临时密钥, 长度为 16 字节 u8 *ex_key: 需要交换的 Key, 长度为 16 字节 如未设置, 则查询到全 0 值 0: 成功其它 : 失败 Espressif 80! /! 153

97 3.10. 云端升级 (FOTA) 接 口 云端升级接 口位于 /ESP8266_NONOS_SDK/include/user_interface.h 和 upgrade.h 中 system_upgrade_userbin_check 查询 user bin uint8 system_upgrade_userbin_check() 0x00 : UPGRADE_FW_BIN1, i.e. user1.bin 0x01 : UPGRADE_FW_BIN2, i.e. user2.bin system_upgrade_flag_set 设置升级状态标志 若调 用 system_upgrade_start 升级, 本接 口需调 用 注意 若 用户调 用 spi_flash_write 自 行行写 Flash 实现升级, 新软件写 入完成后, 将 flag 置为 UPGRADE_FLAG_FINISH, 再调 用 system_upgrade_reboot 重启运 行行新软件 void system_upgrade_flag_set(uint8 flag) uint8 flag: #define UPGRADE_FLAG_IDLE 0x00 #define UPGRADE_FLAG_START 0x01 #define UPGRADE_FLAG_FINISH 0x system_upgrade_flag_check 查询升级状态标志 uint8 system_upgrade_flag_check() #define UPGRADE_FLAG_IDLE 0x00 #define UPGRADE_FLAG_START 0x01 #define UPGRADE_FLAG_FINISH 0x system_upgrade_start 配置, 开始升级 bool system_upgrade_start (struct upgrade_server_info *server) struct upgrade_server_info *server: 升级服务器器的相关 true: 开始升级 false: 已经在升级过程中, 法开始升级 Espressif 81! /! 153

98 system_upgrade_reboot 重启系统, 运 行行新软件 void system_upgrade_reboot (void) Espressif 82! /! 153

99 3.11. Sniffer 相关接 口 Sniffer 接 口位于 /ESP8266_NONOS_SDK/include/user_interface.h wifi_promiscuous_enable 开启混杂模式 (sniffer) 仅 支持在 ESP8266 单 Station 模式下, 开启混杂模式 注意 混杂模式中,ESP8266 Station 和 SoftAP 接 口均失效 若开启混杂模式, 请先调 用 wifi_station_disconnect 确保没有连接 混杂模式中请勿调 用其他 API, 请先调 用 wifi_promiscuous_enable(0) 退出 sniffer void wifi_promiscuous_enable(uint8 promiscuous) uint8 promiscuous 0: 关闭混杂模式 1: 开启混杂模式 示例例 用户可以向乐鑫申请 sniffer demo wifi_promiscuous_set_mac 设置 sniffer 模式时的 MAC 地址过滤, 可过滤出发给指定 MAC 地址的包 ( 也包含 广播包 ) 本接 口需在 wifi_promiscuous_enable(1) 使能混杂模式后调 用 ; 注意 MAC 地址过滤仅对当前这次的 sniffer 有效 ; 如果停 止 sniffer, 又再次 sniffer, 需要重新设置 MAC 地址过滤 示例例 void wifi_promiscuous_set_mac(const uint8_t *address) const uint8_t *address:mac 地址 char ap_mac[6] = {0x16, 0x34, 0x56, 0x78, 0x90, 0xab}; wifi_promiscuous_set_mac(ap_mac); wifi_set_promiscuous_rx_cb 注册混杂模式下的接收数据回调函数, 每收到 一包数据, 都会进 入注册的回调函数 void wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb) wifi_promiscuous_cb_t cb: 回调函数 Espressif 83! /! 153

100 wifi_get_channel 获取信道号 uint8 wifi_get_channel(void) 信道号 wifi_set_channel 设置信道号, 用于混杂模式 bool wifi_set_channel (uint8 channel) uint8 channel: 信道号 true: 成功 false: 失败 Espressif 84! /! 153

101 3.12. SmartConfig 接 口 Smart Config 接 口位于 /ESP8266_NONOS_SDK/include/smartconfig.h AirKiss 接 口位于 /ESP8266_NONOS_SDK/include/airkiss.h 开启 SmartConfig 前, 请先确保 AP 已经开启 smartconfig_start 开启快连模式, 快速连接 ESP8266 Station 到 AP ESP8266 抓取空中特殊的数据包, 包含 目标 AP 的 SSID 和 password 信息, 同时, 用户需要通过 手机或者电脑 广播加密的 SSID 和 password 信息 仅 支持在单 Station 模式下调 用本接 口 SmartConfig 过程中,ESP8266 Station 和 SoftAP 失效 注意 smartconfig_start 未完成之前不不可重复执 行行 smartconfig_start, 请先调 用 smartconfig_stop 结束本次快连 SmartConfig 过程中, 请勿调 用其他 API; 先调 用 smartconfig_stop, 再使 用其他 API typedef enum { SC_STATUS_WAIT = 0, // 连接未开始, 请勿在此阶段开始连接 结构体 SC_STATUS_FIND_CHANNEL, // 请在此阶段开启 APP 进行配对连接 SC_STATUS_GETTING_SSID_PSWD, SC_STATUS_LINK, SC_STATUS_LINK_OVER, // 获取到 IP, 连接路由完成 } sc_status; bool smartconfig_start(sc_callback_t cb, uint8 log) sc_callback_t cb:smartconfig 状态发 生改变时, 进 入回调函数 传 入回调函数的 status 表示 SmartConfig 状态 : - 当 status 为 SC_STATUS_GETTING_SSID_PSWD 时, void *pdata 为 sc_type * 类型的指针变量量, 表示此次配置是 AirKiss 还是 ESP-TOUCH; - 当 status 为 SC_STATUS_LINK 时, void *pdata 为 struct station_config 类型的指针变量量 ; - 当 status 为 SC_STATUS_LINK_OVER 时, void *pdata 是移动端的 IP 地址的指针, 4 个字节 ( 仅 支持在 ESP-TOUCH 方式下, 其他 方式则为 NULL) - 当 status 为其他状态时, void *pdata 为 NULL uint8 log - 1:UART 打印连接过程 - 否则 :UART 仅打印连接结果 打印信息仅供调试使 用, 正常 工作时, 应避免 SmartConfig 过程中进 行行串串 口打印 true: 成功 false: 失败 Espressif 85! /! 153

102 示例例 void ICACHE_FLASH_ATTR smartconfig_done(sc_status status, void *pdata) { switch(status) { case SC_STATUS_WAIT: os_printf("sc_status_wait\n"); break; case SC_STATUS_FIND_CHANNEL: os_printf("sc_status_find_channel\n"); break; case SC_STATUS_GETTING_SSID_PSWD: os_printf("sc_status_getting_ssid_pswd\n"); sc_type *type = pdata; if (*type == SC_TYPE_ESPTOUCH) { os_printf("sc_type:sc_type_esptouch\n"); } else { os_printf("sc_type:sc_type_airkiss\n"); } break; case SC_STATUS_LINK: os_printf("sc_status_link\n"); struct station_config *sta_conf = pdata; wifi_station_set_config(sta_conf); wifi_station_disconnect(); wifi_station_connect(); break; case SC_STATUS_LINK_OVER: os_printf("sc_status_link_over\n"); if (pdata!= NULL) { uint8 phone_ip[4] = {0}; memcpy(phone_ip, (uint8*)pdata, 4); os_printf("phone ip: %d.%d.%d. %d\n",phone_ip[0],phone_ip[1],phone_ip[2],phone_ip[3]); } smartconfig_stop(); break; } } smartconfig_start(smartconfig_done); smartconfig_stop 注意 关闭快连模式, 释放 smartconfig_start 占 用的内存 若快连成功, 连上 目标 AP 后, 调 用本接 口释放 smartconfig_start 占 用的内存 若快连失败, 调 用本接 口退出快连模式, 释放占 用的内存 bool smartconfig_stop(void) true: 成功 false: 失败 smartconfig_set_type 注意 设置快连模式的协议类型 如需调 用本接 口, 请在 smartconfig_start 之前调 用 Espressif 86! /! 153

103 bool smartconfig_set_type(sc_type type) typedef enum { SC_TYPE_ESPTOUCH = 0, SC_TYPE_AIRKISS, SC_TYPE_ESPTOUCH_AIRKISS, } sc_type; true: 成功 false: 失败 airkiss_version 获得 AirKiss 库的版本信息 注意 版本信息的实际 长度未知 const char* airkiss_version(void) AirKiss 库的版本信息 airkiss_lan_recv 用于 AirKiss 内 网发现, 可参考微信官 网内 网发现介绍 内 网发现 大致流程为 : 创建 一个 UDP 传输, 在 UDP 的 espconn_recv_callback 中, 将接 收到的 UDP 报 文传 入 airkiss_lan_recv 函数, 若函数 AIRKISS_LAN_SSDP_REQ, 则调 用 airkiss_lan_pack 打包响应报 文, 通过 UDP 传输回复给发送 方 本函数 用于接收 AirKiss 发来的 UDP 数据包并解析 int airkiss_lan_recv( const void* body, unsigned short length, const airkiss_config_t* config) const void* body: 接收到的 UDP 数据 unsigned short length: 有效的数据 长度 airkiss_config_t* config:airkiss 结构体 >=0: 成功 <0: 失败 具体可参考 airkiss_lan_ret_t Espressif 87! /! 153

104 airkiss_lan_pack 用于 AirKiss 内 网发现, 将 用户数据组织成 AirKiss 内 网探测的 UDP 数据包格式 int airkiss_lan_pack( airkiss_lan_cmdid_t ak_lan_cmdid, void* appid, void* deviceid, void* _datain, unsigned short inlength, void* _dataout, unsigned short* outlength, const airkiss_config_t* config) airkiss_lan_cmdid_t ak_lan_cmdid: 发包的类型 void* appid: 微信公众号, 必须从微信获得 void* deviceid: 设备 ID 值, 必须从微信获得 void* _datain: 待组包的 用户数据 unsigned short inlength: 用户数据 长度 void* _dataout: 用户数据完成 AirKiss 内 网探测组包后的数据 unsigned short* outlength: 组包后的数据 长度 const airkiss_config_t* config:airkiss 结构体 >=0: 成功 <0: 失败 具体可参考 airkiss_lan_ret_t Espressif 88! /! 153

105 3.13. SNTP 接 口 SNTP 接 口位于 /ESP8266_NONOS_SDK/include/sntp.h sntp_setserver 通过 IP 地址设置 SNTP 服务器器, 一共最多 支持设置 3 个 SNTP 服务器器 void sntp_setserver(unsigned char idx, ip_addr_t *addr) unsigned char idx:sntp 服务器器编号, 最多 支持 3 个 SNTP 服务器器 (0 ~ 2);0 号为主服务器器,1 号和 2 号为备 用服务器器 ip_addr_t *addr:ip 地址 ; 用户需 自 行行确保, 传 入的是合法 SNTP 服务器器 sntp_getserver 查询 SNTP 服务器器的 IP 地址, 对应的设置接 口为 :sntp_setserver ip_addr_t sntp_getserver(unsigned char idx) unsigned char idx:sntp 服务器器编号, 最多 支持 3 个 SNTP 服务器器 (0 ~ 2) IP 地址 sntp_setservername 通过域名设置 SNTP 服务器器, 一共最多 支持设置 3 个 SNTP 服务器器 void sntp_setservername(unsigned char idx, char *server) unsigned char idx:sntp 服务器器编号, 最多 支持 3 个 SNTP 服务器器 (0 ~ 2);0 号为主服务器器,1 号和 2 号为备 用服务器器 char *server: 域名 ; 用户需 自 行行确保, 传 入的是合法 SNTP 服务器器 sntp_getservername 查询 SNTP 服务器器的域名, 仅 支持查询通过 sntp_setservername 设置的 SNTP 服务器器 char * sntp_getservername(unsigned char idx) unsigned char idx:sntp 服务器器编号, 最多 支持 3 个 SNTP 服务器器 (0 ~ 2) 服务器器域名 sntp_init SNTP 初始化 Espressif 89! /! 153

106 void sntp_init(void) sntp_stop SNTP 关闭 void sntp_stop(void) sntp_get_current_timestamp 查询当前距离基准时间 ( :00:00 GMT + 8) 的时间戳, 单位 : 秒 uint32 sntp_get_current_timestamp() 距离基准时间的时间戳 sntp_get_real_time 查询实际时间 (GMT + 8) char* sntp_get_real_time(long t) long t: 与基准时间相距的时间戳 实际时间 sntp_set_timezone 注意 设置时区信息 调 用本接 口前, 请先调 用 sntp_stop bool sntp_set_timezone (sint8 timezone) sint8 timezone: 时区值, 范围 :-11 ~ 13 示例例 true: 成功 false: 失败 sntp_stop(); if( true == sntp_set_timezone(-5) ) { sntp_init(); } Espressif 90! /! 153

107 sntp_get_timezone 查询时区信息 sint8 sntp_get_timezone (void) 时区值, 范围 :-11 ~ SNTP 示例例 Step 1. enable sntp ip_addr_t *addr = (ip_addr_t *)os_zalloc(sizeof(ip_addr_t)); sntp_setservername(0, us.pool.ntp.org ); // set server 0 by domain name sntp_setservername(1, ntp.sjtu.edu.cn ); // set server 1 by domain name ipaddr_aton( , addr); sntp_setserver(2, addr); // set server 2 by IP address sntp_init(); os_free(addr); Step 2. set a timer to check sntp timestamp LOCAL os_timer_t sntp_timer; os_timer_disarm(&sntp_timer); os_timer_setfn(&sntp_timer, (os_timer_func_t *)user_check_sntp_stamp, NULL); os_timer_arm(&sntp_timer, 100, 0); Step 3. timer callback void ICACHE_FLASH_ATTR user_check_sntp_stamp(void *arg){ uint32 current_stamp; current_stamp = sntp_get_current_timestamp(); if(current_stamp == 0){ os_timer_arm(&sntp_timer, 100, 0); } else{ os_timer_disarm(&sntp_timer); os_printf( sntp: %d, %s \n,current_stamp, sntp_get_real_time(current_stamp)); } } Espressif 91! /! 153

108 3.14. WPA2-Enterprise 接 口 ESP8266 Station 接 口 支持连接到 WPA2_Enterprise 企业级加密的 AP WPA2_Enterprise 接 口位于 /ESP8266_NONOS_SDK/include/wpa2_enterprise.h wifi_station_set_wpa2_enterprise_auth 使能 WPA2_Enterprise 企业级加密的验证 连接 WPA2_Enterprise AP, 需调 用 wifi_station_set_wpa2_enterprise_auth(1); 使能验 证 之后如再需连接普通 AP, 则需要先调 用 wifi_station_set_wpa2_enterprise_auth(0); 清 除状态 int wifi_station_set_wpa2_enterprise_auth(int enable) int enable 0: 清除当前 WPA2_Enterprise 状态 ; 非 0: 使能 WPA2_Enterprise 企业级加密的验证 0: 成功其它 : 失败 wifi_station_set_enterprise_cert_key 设置 ESP8266 Station 接 口连接 WPA2_Enterprise AP 所需的 用户证书及密钥, 用于 EAP-TLS 认证 支持 WPA2-ENTERPRISE AP 需占 用 26 KB 以上的内存, 调 用本接 口时请注意内存是否 足够 目前 WPA2-ENTERPRISE 只 支持 非加密的私钥 文件和证书 文件, 且仅 支持 PEM 格式 - 支持的证书 文件头信息为 : BEGIN CERTIFICATE 注意 - 支持的私钥 文件头信息为 : BEGIN RSA PRIVATE KEY 或者 BEGIN PRIVATE KEY 请在连接 WPA2_Enterprise AP 之前调 用本接 口设置私钥 文件和证书 文件, 在成功连接 AP 后先调 用 wifi_station_clear_enterprise_cert_key 清除内部状态, 应 用层再释放私钥 文 件和证书 文件信息 如果遇到加密的私钥 文件, 请使 用 openssl pkey 命令改为 非加密 文件使 用, 或者使 用 openssl rsa 等命令, 对某些私钥 文件进 行行加密 - 非加密的转换( 或起始 TAG 转化 ) int wifi_station_set_enterprise_cert_key( u8 *client_cert, int client_cert_len, u8 *private_key, int private_key_len, u8 *private_key_passwd, int private_key_passwd_len) Espressif 92! /! 153

109 uint8 *client_cert: 十六进制数组的证书指针 int client_cert_len: 证书 长度 uint8 *private_key: 十六进制数组的私钥指针, 暂不不 支持超过 2048 的私钥 int private_key_len: 私钥 长度, 请勿超过 2048 uint8 *private_key_passwd: 私钥的提取密码, 目前暂不不 支持, 请传 入 NULL 示例例 int private_key_passwd_len: 提取密码的 长度, 目前暂不不 支持, 请传 入 0 0: 成功 非 0: 失败假设私钥 文件的信息为 BEGIN PRIVATE KEY 那么对应的数组为 :uint8 key[]={0x2d, 0x2d, 0x2d, 0x2d, 0x2d, 0x42, 0x45, 0x47, 0x00 }; 即各字符的 ASCII 码, 请注意, 数组必须添加 0x00 作为结尾 wifi_station_clear_enterprise_cert_key 释放连接 WPA2_Enterprise AP 使 用 用户证书和密钥所占 用的资源, 并清除相关状态 void wifi_station_clear_enterprise_cert_key (void) wifi_station_set_enterprise_ca_cert 设置 ESP8266 Station 接 口连接 WPA2_Enterprise AP 使 用的根证书 EAP-TTLS/PEAP 认证 方法可选对根证书进 行行验证 int wifi_station_set_enterprise_ca_cert(u8 *ca_cert, int ca_cert_len) u8 *ca_cert: 十六进制数组的根证书指针 int ca_cert_len: 根证书 长度 0: 成功其它 : 失败 wifi_station_clear_enterprise_ca_cert 释放连接 WPA2_Enterprise AP 使 用根证书占 用的资源, 并清除相关状态 void wifi_station_clear_enterprise_ca_cert (void) wifi_station_set_enterprise_username 设置连接 WPA2_Enterprise AP 时,ESP8266 Station 的 用户名 Espressif 93! /! 153

110 WPA2_Enterprise 企业级加密 方法调 用本接 口设置 用户身份, 注意 对于 EAP-TTLS 以及 EAP-PEAP 认证必须设置, 并且是 用在了了认证的第 二阶段, 只有认证 服务器器 支持的 用户身份才能通过认证 对于 EAP-TLS 认证 方法则为可选项, 即使没有设置 用户名, 也可以通过匿匿名的身份通过验 证 int wifi_station_set_enterprise_username (u8 *username, int len) u8 *username: 用户名称 int len: 名称 长度 0: 成功其它 : 失败 wifi_station_clear_enterprise_username 释放连接 WPA2_Enterprise AP 设置 用户名占 用的资源, 并清除相关状态 void wifi_station_clear_enterprise_username (void) wifi_station_set_enterprise_password 设置 用户密码, 用于通过 EAP-TTLS/EAP-PEAP 认证 方法 int wifi_station_set_enterprise_password (u8 *password, int len) u8 *password: 用户密码 int len: 密码 长度 0: 成功其它 : 失败 wifi_station_clear_enterprise_password 释放连接 WPA2_Enterprise AP 设置密码占 用的资源, 并清除相关状态 void wifi_station_clear_enterprise_password (void) wifi_station_set_enterprise_new_password 设置新 用户密码, 针对 MSCHAPV2 方法 int wifi_station_set_enterprise_new_password (u8 *new_password, int len) Espressif 94! /! 153

111 u8 *new_password: 新 用户密码 int len: 密码 长度 0: 成功其它 : 失败 wifi_station_clear_enterprise_new_password 释放连接 WPA2_Enterprise AP 设置新 用户密码占 用的资源, 并清除相关状态 void wifi_station_clear_enterprise_new_password (void) wifi_station_set_enterprise_disable_time_check 设置认证时, 是否检查过期时间 默认情况下, 认证过程中不不检查过期时间 void wifi_station_set_enterprise_disable_time_check(bool disable) bool disable true: 不不检查过期时间 false: 检查过期时间, 需调 用 wpa2_enterprise_set_user_get_time 注册回调函数 wifi_station_get_enterprise_disable_time_check 查询认证时, 是否检查过期时间 bool wifi_station_get_enterprise_disable_time_check (void) true: 不不检查过期时间 false: 检查过期时间 wpa2_enterprise_set_user_get_time 设置认证过程中从 用户获得时间的回调函数 需调 用 wifi_station_set_enterprise_disable_time_check(false); 使能检查过期时间 void wpa2_enterprise_set_user_get_time(get_time_func_t cb) get_time_func_t cb: 回调函数 Espressif 95! /! 153

112 static int sys_get_current_time(struct os_time *t) 示例例 { t->sec = CURRENT_TIME; // User set current time. return 0; } //Set Callback wpa2_enterprise_set_user_get_time(sys_get_current_time); //Enable Time check wifi_station_set_enterprise_disable_time_check(false); 示例例流程如需连接 WPA2_Enterprise 加密的 AP, 流程如下 : 1. wifi_station_set_config 配置需连接的 AP 信息 2. wifi_station_set_wpa2_enterprise_auth(1); 使能 WPA2_Enterprise 加密验证 2.1. 若为 EAP-TLS 认证, 调 用 wifi_station_set_enterprise_cert_key 设置证书和密钥 可选调 用 wifi_station_set_enterprise_username 设置 用户名 2.2. 若为 EAP-TTLS 或 EAP-PEAP 认证, 调 用 wifi_station_set_enterprise_username 以及 wifi_station_set_enterprise_password, 设置 用户名和密码 可选调 用 wifi_station_set_enterprise_ca_cert 设置根证书 3. wifi_station_connnect 连接 AP 4. 成功连接 AP 或连接 AP 失败并不不再重试后, 调 用 wifi_station_clear_enterprise_xxx 对应接 口释放资源 Espressif 96! /! 153

113 ! 4. TCP/UDP 接 口 4. TCP/UDP 接 口 位于 ESP8266_NONOS_SDK/include/espconn.h 网络相关接 口可分为以下 几类 : 通 用接 口 :TCP 和 UDP 均可以调 用的接 口 TCP APIs: 仅建 立 TCP 连接时, 使 用的接 口 UDP APIs: 仅收发 UDP 包时, 使 用的接 口 mdns APIs:mDNS 相关接 口 4.1. 通 用接 口 espconn_delete 删除传输连接 对应创建传输的接 口如下 : 注意 TCP:espconn_accept UDP:espconn_create sint8 espconn_delete(struct espconn *espconn) struct espconn *espconn: 对应 网络传输的结构体 0: 成功其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 网络传输 ESPCONN_INPROGRESS: espconn 对应的 网络连接仍未断开, 请先调 用 espconn_disconnect 断开连接, 再进 行行删除 espconn_gethostbyname DNS err_t espconn_gethostbyname( struct espconn *pespconn, const char *hostname, ip_addr_t *addr, dns_found_callback found ) Espressif 97! /!

114 ! 4. TCP/UDP 接 口 struct espconn *espconn: 对应 网络传输的结构体 const char *hostname: 域名字符串串的指针 ip_addr_t *addr:ip 地址 dns_found_callback found:dns 回调函数 err_t ESPCONN_OK: 成功 ESPCONN_ISCONN: 失败, 错误码含义 : 已经连接 ESPCONN_ARG: 失败, 错误码含义 : 未找到 espconn 对应的 网络传输请参考 IoT_Demo: ip_addr_t esp_server_ip; LOCAL void ICACHE_FLASH_ATTR user_esp_platform_dns_found(const char *name, ip_addr_t *ipaddr, void *arg) { struct espconn *pespconn = (struct espconn *)arg; 示例例 if (ipaddr!= NULL) os_printf(user_esp_platform_dns_found %d.%d.%d.%d/n, *((uint8 *)&ipaddr->addr), *((uint8 *)&ipaddr->addr + 1), *((uint8 *)&ipaddr->addr + 2), *((uint8 *)&ipaddr->addr + 3)); } void dns_test(void) { espconn_gethostbyname(pespconn, iot.espressif.cn, &esp_server_ip, user_esp_platform_dns_found); } espconn_port 获取 ESP8266 可 用的端 口 uint32 espconn_port(void) 端 口号 espconn_regist_sentcb 注册 网络数据发送成功的回调函数 sint8 espconn_regist_sentcb( struct espconn *espconn, espconn_sent_callback sent_cb ) struct espconn *espconn: 对应 网络传输的结构体 espconn_connect_callback connect_cb: 成功接收 网络数据的回调函数 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 网络传输 Espressif 98! /!

115 ! 4. TCP/UDP 接 口 espconn_regist_recvcb 注册成功接收 网络数据的回调函数 sint8 espconn_regist_recvcb( struct espconn *espconn, espconn_recv_callback recv_cb ) struct espconn *espconn: 对应 网络传输的结构体 espconn_connect_callback connect_cb: 成功接收 网络数据的回调函数 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 网络传输 espconn_sent_callback 网络数据发送成功的回调函数, 由 espconn_regist_sentcb 注册 void espconn_sent_callback (void *arg) void *arg: 回调函数的, 网络传输的结构体 espconn 指针 注意, 本指针为底层维护的指针, 不不同回调传 入的指针地址可能不不 一样, 请勿依此判断 网络连 接 可根据 espconn 结构体中的 remote_ip, remote_port 判断多连接中的不不同 网络传输 espconn_recv_callback 成功接收 网络数据的回调函数, 由 espconn_regist_recvcb 注册 void espconn_recv_callback ( void *arg, char *pdata, unsigned short len ) void *arg: 回调函数的, 网络传输结构体 espconn 指针 注意, 本指针为底层维护的 指针, 不不同回调传 入的指针地址可能不不 一样, 请勿依此判断 网络连接 可根据 espconn 结 构体中的 remote_ip remote_port 判断多连接中的不不同 网络传输 char *pdata: 接收到的数据 unsigned short len: 接收到的数据 长度 espconn_get_connection_info 查询某个 TCP 连接或者 UDP 传输的远端信息 一般在 espconn_recv_callback 中调 用 sint8 espconn_get_connection_info( struct espconn *espconn, remot_info **pcon_info, uint8 typeflags ) Espressif 99! /!

116 ! 4. TCP/UDP 接 口 struct espconn *espconn: 对应 网络连接的结构体 示例例 remot_info **pcon_info: 连接 client 信息 uint8 typeflags - 0: 正常 server - 1:SSL server 0: 成功其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 void user_udp_recv_cb(void *arg, char *pusrdata, unsigned short length) { struct espconn *pesp_conn = arg; remot_info *premot = NULL; if (espconn_get_connection_info(pesp_conn,&premot,0) == ESPCONN_OK){ pesp_conn->proto.tcp->remote_port = premot->remote_port; pesp_conn->proto.tcp->remote_ip[0] = premot->remote_ip[0]; pesp_conn->proto.tcp->remote_ip[1] = premot->remote_ip[1]; pesp_conn->proto.tcp->remote_ip[2] = premot->remote_ip[2]; pesp_conn->proto.tcp->remote_ip[3] = premot->remote_ip[3]; espconn_sent(pesp_conn, pusrdata, os_strlen(pusrdata)); } } espconn_send 注意 通过 WiFi 发送数据 一般情况, 请在前 一包数据发送成功, 进 入 espconn_sent_callback 后, 再调 用 espconn_send 发送下 一包数据 如果是 UDP 传输, 请在每次调 用 espconn_send 前, 设置 espconn->proto.udp->remote_ip 和 remote_port, 因为 UDP 连接, 远端信息可能被更更改 sint8 espconn_send( struct espconn *espconn, uint8 *psent, uint16 length ) struct espconn *espconn: 对应 网络传输的结构体 uint8 *psent: 发送的数据 uint16 length: 发送的数据 长度 Espressif 100! /!

117 ! 4. TCP/UDP 接 口 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 网络传输 ESPCONN_MEM: 空间不不 足 ESPCONN_MAXNUM: 底层发包缓存已满, 发包失败 ESPCONN_IF:UDP 发包失败 espconn_sent [@deprecated] 本接 口不不建议使 用, 建议使 用 espconn_send 代替 注意 通过 WiFi 发送数据 一般情况, 请在前 一包数据发送成功, 进 入 espconn_sent_callback 后, 再调 用 espconn_send 发送下 一包数据 如果是 UDP 传输, 请在每次调 用 espconn_send 前, 设置 espconn->proto.udp->remote_ip 和 remote_port, 因为 UDP 连接, 远端信息可能被更更改 sint8 espconn_sent( struct espconn *espconn, uint8 *psent, uint16 length ) struct espconn *espconn: 对应 网络传输的结构体 uint8 *psent: 发送的数据 uint16 length: 发送的数据 长度 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 网络传输 ESPCONN_MEM: 空间不不 足 ESPCONN_MAXNUM: 底层发包缓存已满, 发包失败 ESPCONN_IF:UDP 发包失败 Espressif 101! /!

118 ! 4. TCP/UDP 接 口 4.2. TCP 接 口 TCP 接 口仅 用于 TCP 连接, 请勿 用于 UDP 传输 espconn_accept 创建 TCP server, 建 立侦听 sint8 espconn_accept(struct espconn *espconn) struct espconn *espconn: 对应 网络连接的结构体 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 ESPCONN_MEM: 空间不不 足 ESPCONN_ISCONN: 连接已经建 立 espconn_regist_time 注册 ESP8266 TCP server 超时时间, 时间值仅作参考, 并不不精确 请在 espconn_accept 之后, 连接未建 立之前, 调 用本接 口 本接 口不不能 用于 SSL 连接 注意 如果超时时间设置为 0,ESP8266 TCP server 将始终不不会断开已经不不与它通信的 TCP client, 不不建议这样使 用 sint8 espconn_regist_time( struct espconn *espconn, uint32 interval, uint8 type_flag ) struct espconn *espconn: 对应 网络连接的结构体 uint32 interval: 超时时间, 单位 : 秒, 最 大值 :7200 秒 uint8 type_flag - 0: 对所有 TCP 连接 生效 - 1: 仅对某 一 TCP 连接 生效 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_connect 连接 TCP server(esp8266 作为 TCP client) 注意 如果 espconn_connect 失败, 非零值, 连接未建 立, 不不会进 入任何 espconn callback 建议使 用 espconn_port 接 口, 设置 一个可 用的端 口号 sint8 espconn_connect(struct espconn *espconn) struct espconn *espconn: 对应 网络连接的结构体 Espressif 102! /!

119 ! 4. TCP/UDP 接 口 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 ESPCONN_MEM: 空间不不 足 ESPCONN_ISCONN: 连接已经建 立 ESPCONN_RTE: 路路由异常 espconn_regist_connectcb 注册 TCP 连接成功建 立后的回调函数 sint8 espconn_regist_connectcb( struct espconn *espconn, espconn_connect_callback connect_cb ) struct espconn *espconn: 对应 网络连接的结构体 espconn_connect_callback connect_cb: 成功建 立 TCP 连接后的回调函数 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_connect_callback 成功建 立 TCP 连接的回调函数, 由 espconn_regist_connectcb 注册 ESP8266 作为 TCP server 侦听到 TCP client 连 入 ; 或者 ESP8266 作为 TCP client 成功与 TCP server 建 立连接 void espconn_connect_callback (void *arg) void *arg: 回调函数的, 对应 网络连接的结构体 espconn 指针 注意, 本指针为底层维护的指针, 不不同回调传 入的指针地址可能不不 一样, 请勿依此判断 网络连接 可根据 espconn 结构体中的 remote_ip, remote_port 判断多连接中的不不同 网络传输 espconn_set_opt 设置 TCP 连接的相关配置, 对应清除配置标志位的接 口为 espconn_clear_opt SSL 连接不不 支持使 用本接 口 注意 一般情况下, 需调 用本接 口 ; 如需设置 espconn_set_opt 请在 espconn_connect_callback 中调 用 sint8 espconn_set_opt( struct espconn *espconn, uint8 opt ) Espressif 103! /!

120 ! 4. TCP/UDP 接 口 struct espconn *espconn: 对应 网络连接的结构体 uint8 opt:tcp 连接的相关配置, 参考 espconn_option - bit 0:1,TCP 连接断开时, 及时释放内存, 需等待 2 分钟才释放占 用内存 ; - bit 1:1, 关闭 TCP 数据传输时的 nalge 算法 ; - bit 2:1, 使能 write finish callback, 进 入此回调表示 espconn_send 要发送的数据已经写 入 2920 字节的 write buffer 等待发送或已经发送 ; - bit 3:1, 使能 keep alive; 0: 成功其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_clear_opt 结构体 清除 TCP 连接的相关配置 sint8 espconn_clear_opt( struct espconn *espconn, uint8 opt ) enum espconn_option{ } ESPCONN_START = 0x00, ESPCONN_REUSEADDR = 0x01, ESPCONN_NODELAY = 0x02, ESPCONN_COPY = 0x04, ESPCONN_KEEPALIVE = 0x08, ESPCONN_END struct espconn *espconn: 对应 网络连接的结构体 uint8 opt: 清除 TCP 连接的相关配置, 参考 espconn_option 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_set_keepalive 注意 设置 TCP keep alive 的 一般情况下, 不不需要调 用本接 口 如果设置, 请在 espconn_connect_callback 中调 用, 并先设置 espconn_set_opt 使能 keep alive sint8 espconn_set_keepalive(struct espconn *espconn, uint8 level, void* optarg) Espressif 104! /!

121 ! 4. TCP/UDP 接 口 enum espconn_level{ ESPCONN_KEEPIDLE, 结构体 ESPCONN_KEEPINTVL, ESPCONN_KEEPCNT } struct espconn *espconn: 对应 网络连接的结构体 uint8 level: 默认设置为每隔 ESPCONN_KEEPIDLE 时 长进 行行 一次 keep alive 探查, 如果报 文响应, 则每隔 ESPCONN_KEEPINTVL 时 长探查 一次, 最多探查 ESPCONN_KEEPCNT 次 ; 若始 终响应, 则认为 网络连接断开, 释放本地连接相关资源, 进 入 espconn_reconnect_callback 注意, 时间间隔设置并不不可靠精准, 仅供参考, 受其他 高优 先级任务执 行行的影响 说明如下 : - ESPCONN_KEEPIDLE: 设置进 行行 keep alive 探查的时间间隔, 单位 : 秒 - ESPCONN_KEEPINTVL:keep alive 探查过程中, 报 文的时间间隔, 单位 : 秒 - ESPCONN_KEEPCNT: 每次 keep alive 探查, 发送报 文的最 大次数 void* optarg: 设置值 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_get_keepalive 查询 TCP keep alive 的 sint8 espconn_set_keepalive(struct espconn *espconn, uint8 level, void* optarg) enum espconn_level{ ESPCONN_KEEPIDLE, 结构体 ESPCONN_KEEPINTVL, ESPCONN_KEEPCNT } struct espconn *espconn: 对应 网络连接的结构体 uint8 level - ESPCONN_KEEPIDLE: 设置进 行行 keep alive 探查的时间间隔, 单位 : 秒 - ESPCONN_KEEPINTVL:keep alive 探查过程中, 报 文的时间间隔, 单位 : 秒 - ESPCONN_KEEPCNT: 每次 keep alive 探查, 发送报 文的最 大次数 void* optarg: 设置值 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_reconnect_callback TCP 连接异常断开时的回调函数, 相当于出错处理理回调, 由 espconn_regist_reconcb 注册 void espconn_reconnect_callback (void *arg, sint8 err) Espressif 105! /!

122 ! 4. TCP/UDP 接 口 void *arg: 回调函数的, 对应 网络连接的结构体 espconn 指针 注意, 本指针为底层维护的指针, 不不同回调传 入的指针地址可能不不 一样, 请勿依此判断 网络连接 可根据 espconn 结构体中的 remote_ip remote_port 判断多连接中的不不同 网络传输 sint8 err: 异常断开的错误码 - ESCONN_TIMEOUT: 超时出错断开 - ESPCONN_ABRT:TCP 连接异常断开 - ESPCONN_RST:TCP 连接复位断开 - ESPCONN_CLSD:TCP 连接在断开过程中出错, 异常断开 - ESPCONN_CONN:TCP 未连接成功 - ESPCONN_HANDSHAKE:TCP SSL 握 手失败 - ESPCONN_PROTO_MSG:SSL 应 用数据处理理异常 espconn_regist_reconcb 注意 注册 TCP 连接发 生异常断开时的回调函数, 可以在回调函数中进 行行重连 espconn_reconnect_callback 类似于出错处理理回调, 任何阶段出错时, 均会进 入此回调 例例如,espconn_sent 失败, 则认为 网络连接异常, 也会进 入 espconn_reconnect_callback; 用户可在 espconn_reconnect_callback 中 自 行行定义出错处理理 sint8 espconn_regist_reconcb( struct espconn *espconn, espconn_reconnect_callback recon_cb ) struct espconn *espconn: 对应 网络连接的结构体 espconn_reconnect_callback recon_cb: 回调函数 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_disconnect 注意 断开 TCP 连接请勿在 espconn 的任何 callback 中调 用本接 口断开连接 如有需要, 可以在 callback 中使 用任务触发调 用本接 口断开连接 sint8 espconn_disconnect(struct espconn *espconn) struct espconn *espconn: 对应 网络连接的结构体 0: 成功其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 Espressif 106! /!

123 ! 4. TCP/UDP 接 口 espconn_regist_disconcb 注册 TCP 连接正常断开成功的回调函数 sint8 espconn_regist_disconcb( struct espconn *espconn, espconn_connect_callback discon_cb ) struct espconn *espconn: 对应 网络连接的结构体 espconn_connect_callback connect_cb: 回调函数 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_abort 注意 强制断开 TCP 连接请勿在 espconn 的任何 callback 中调 用本接 口断开连接 如有需要, 可以在 callback 中使 用任务触发调 用本接 口断开连接 sint8 espconn_abort(struct espconn *espconn) struct espconn *espconn: 对应 网络连接的结构体 0: 成功其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_regist_write_finish 注册所有需发送的数据均成功写 入 write buffer 后的回调函数 请先调 用 espconn_set_opt 使能 write buffer 本接 口不不能 用于 SSL 连接 write buffer 用于缓存 espconn_send 将发送的数据, 最多缓存 8 包数据,write buffer 的容量量 注意 为 2920 字节 由 espconn_set_opt 设置使能 write_finish_callback 回调 对发送速度有要求时, 可以在 write_finish_callback 中调 用 espconn_send 发送下 一包, 需等到 espconn_sent_callback sint8 espconn_regist_write_finish ( struct espconn *espconn, espconn_connect_callback write_finish_fn ) struct espconn *espconn: 对应 网络连接的结构体 espconn_connect_callback write_finish_fn: 回调函数 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 Espressif 107! /!

124 ! 4. TCP/UDP 接 口 espconn_tcp_get_max_con 查询允许的 TCP 最 大连接数 uint8 espconn_tcp_get_max_con(void) 允许的 TCP 最 大连接数 espconn_tcp_set_max_con 设置允许的 TCP 最 大连接数 在内存 足够的情况下, 建议不不超过 10 默认值为 5 sint8 espconn_tcp_set_max_con(uint8 num) uint8 num: 允许的 TCP 最 大连接数 0: 成功其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_tcp_get_max_con_allow 查询 ESP8266 某个 TCP server 最多允许连接的 TCP client 数 目 sint8 espconn_tcp_get_max_con_allow(struct espconn *espconn) struct espconn *espconn: 对应 TCP server 的结构体 >0: 最多允许连接的 TCP client 数 目 <0: 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_tcp_set_max_con_allow 设置 ESP8266 某个 TCP server 最多允许连接的 TCP client 数 目 sint8 espconn_tcp_set_max_con_allow(struct espconn *espconn, uint8 num) struct espconn *espconn: 对应 TCP server 的结构体 uint8 num: 允许的 TCP 最 大连接数 0: 成功其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_recv_hold 注意 阻塞 TCP 接收数据调 用本接 口会逐渐减 小 TCP 的窗 口, 并不不是即时阻塞, 因此建议预留留 1460*5 字节左右的空间时候调 用, 且本接 口可以反复调 用 sint8 espconn_recv_hold(struct espconn *espconn) Espressif 108! /!

125 ! 4. TCP/UDP 接 口 struct espconn *espconn: 对应 网络连接的结构体 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_recv_unhold 注意 解除 TCP 收包阻塞, 即对应的阻塞接 口 espconn_recv_hold 本接 口实时 生效 sint8 espconn_recv_unhold(struct espconn *espconn) struct espconn *espconn: 对应 网络连接的结构体 0: 成功其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 TCP 连接 espconn_secure_accept 创建 SSL server, 侦听 SSL 握 手 目前仅 支持建 立 一个 SSL server, 本接 口只能调 用 一次, 并且仅 支持连 入 一个 SSL client 如果 SSL 加密 一包数据 大于 espconn_secure_set_size 设置的缓存空间,ESP8266 法处 理理,SSL 连接断开, 进 入 espconn_reconnect_callback 注意 SSL 相关接 口与普通 TCP 接 口底层处理理不不 一致, 请不不要混 用 SSL 连接时, 仅 支持使 用 espconn_secure_xxx 系列列接 口和 espconn_regist_xxxcb 系列列注册回调函数的接 口, 以及 espconn_port 获得 一个空闲端 口 如需创建 SSL server, 必须先调 用 espconn_secure_set_default_certificate 和 espconn_secure_set_default_private_key 传 入证书和密钥 sint8 espconn_secure_accept(struct espconn *espconn) struct espconn *espconn: 对应 网络连接的结构体 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 SSL 连接 ESPCONN_MEM: 空间不不 足 ESPCONN_ISCONN: 连接已经建 立 espconn_secure_delete 删除 ESP8266 作为 SSL server 的连接 sint8 espconn_secure_delete(struct espconn *espconn) struct espconn *espconn: 对应 网络连接的结构体 Espressif 109! /!

126 ! 4. TCP/UDP 接 口 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 SSL 连接 ESPCONN_INPROGRESS: espconn 对应的 SSL 连接仍未断开, 请先调 用 espconn_secure_disconnect 断开连接, 再进 行行删除 espconn_secure_set_size 设置加密 (SSL) 数据缓存空间的 大 小 默认缓存 大 小为 2KB; 如需更更改, 请在加密 (SSL) 连接建 立前调 用 : 注意 在 espconn_secure_accept(esp8266 作为 SSL server) 之前调 用 ; 或者 espconn_secure_connect(esp8266 作为 SSL client) 之前调 用 bool espconn_secure_set_size (uint8 level, uint16 size) uint8 level: 设置 ESP8266 SSL server/client - 0x01:SSL client - 0x02:SSL server - 0x03:SSL client 和 SSL server uint16 size: 加密数据缓存的空间 大 小, 取值范围 :1 ~ 8192, 单位 : 字节, 默认值为 2048 true: 成功 false: 失败 espconn_secure_get_size 查询加密 (SSL) 数据缓存空间的 大 小 sint16 espconn_secure_get_size (uint8 level) uint8 level: 设置 ESP8266 SSL server/client - 0x01:SSL client - 0x02:SSL server - 0x03:SSL client 和 SSL server 加密 (SSL) 数据缓存空间的 大 小 Espressif 110! /!

127 ! 4. TCP/UDP 接 口 espconn_secure_connect 加密 (SSL) 连接到 TCP SSL server(esp8266 作为 TCP SSL client) 如果 espconn_secure_connect 失败, 非零值, 连接未建 立, 不不会进 入任何 espconn callback 目前 ESP8266 作为 SSL client 仅 支持 一个连接, 本接 口只能调 用 一次, 或者调 用 espconn_secure_disconnect 断开前 一次连接, 才可以再次调 用本接 口建 立 SSL 连接 ; 注意 如果 SSL 加密 一包数据 大于 espconn_secure_set_size 设置的缓存空间,ESP8266 法处 理理,SSL 连接断开, 进 入 espconn_reconnect_callback SSL 相关接 口与普通 TCP 接 口底层处理理不不 一致, 请不不要混 用 SSL 连接时, 仅 支持使 用 espconn_secure_xxx 系列列接 口和 espconn_regist_xxxcb 系列列注册回调函数的接 口, 以及 espconn_port 获得 一个空闲端 口 sint8 espconn_secure_connect (struct espconn *espconn) struct espconn *espconn: 对应 网络连接的结构体 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 SSL 连接 ESPCONN_MEM: 空间不不 足 ESPCONN_ISCONN: 连接已经建 立 espconn_secure_send 注意 发送加密数据 (SSL) 请在上 一包数据发送完成, 进 入 espconn_sent_callback 后, 再发下 一包数据 每 一包数据明 文的上限值为 1024 字节, 加密后的报 文上限值是 1460 字节 sint8 espconn_secure_send ( struct espconn *espconn, uint8 *psent, uint16 length ) struct espconn *espconn: 对应 网络连接的结构体 uint8 *psent: 发送的数据 uint16 length: 发送的数据 长度 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 SSL 连接 Espressif 111! /!

128 ! 4. TCP/UDP 接 口 espconn_secure_sent 本接 口不不建议使 用, 建议使 用 espconn_secure_send 代替 注意 发送加密数据 (SSL) 请在上 一包数据发送完成, 进 入 espconn_sent_callback 后, 再发下 一包数据 每 一包数据明 文的上限值为 1024 字节, 加密后的报 文上限值是 1460 字节 sint8 espconn_secure_sent ( struct espconn *espconn, uint8 *psent, uint16 length ) struct espconn *espconn: 对应 网络连接的结构体 uint8 *psent: 发送的数据 uint16 length: 发送的数据 长度 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 SSL 连接 espconn_secure_disconnect 注意 断开加密连接 (SSL) 请勿在 espconn 的任何 callback 中调 用本接 口断开连接 如有需要, 可以在 callback 中使 用任务触发调 用本接 口断开连接 sint8 espconn_secure_disconnect(struct espconn *espconn) struct espconn *espconn: 对应 网络连接的结构体 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 SSL 连接 espconn_secure_ca_enable 开启 SSL CA 认证 CA 认证, 默认关闭, 详细介绍可参考 文档 ESP8266 SSL 加密使 用 手册 注意 如需调 用本接 口, 请在加密 (SSL) 连接建 立前调 用 : - 在 espconn_secure_accept(esp8266 作为 SSL server) 之前调 用 ; - 或者 espconn_secure_connect(esp8266 作为 SSL client) 之前调 用 bool espconn_secure_ca_enable (uint8 level, uint32 flash_sector) Espressif 112! /!

129 ! 4. TCP/UDP 接 口 uint8 level: 设置 ESP8266 SSL server/client - 0x01:SSL client - 0x02:SSL server - 0x03:SSL client 和 SSL server uint32 flash_sector: 设置 CA 证书 esp_ca_cert.bin 烧录到 Flash 的位置 例例如, 传 入 0x3B, 则对应烧录到 Flash 0x7B000 true: 成功 false: 失败 espconn_secure_ca_disable 关闭 SSL CA 认证 CA 认证, 默认关闭, 详细介绍可参考 文档 ESP8266 SSL 加密使 用 手册 注意 如需调 用本接 口, 请在加密 (SSL) 连接建 立前调 用 : - 在 espconn_secure_accept(esp8266 作为 SSL server) 之前调 用 ; - 或者 espconn_secure_connect(esp8266 作为 SSL client) 之前调 用 bool espconn_secure_ca_disable (uint8 level) uint8 level: 设置 ESP8266 SSL server/client - 0x01:SSL client - 0x02:SSL server - 0x03:SSL client 和 SSL server true: 成功 false: 失败 espconn_secure_cert_req_enable 注意 使能 ESP8266 作为 SSL client 时的证书认证 证书认证, 默认关闭 如果服务器器端不不要求认证证书, 则需调 用本接 口 如需调 用本接 口, 请在 espconn_secure_connect 之前调 用 bool espconn_secure_cert_req_enable (uint8 level, uint32 flash_sector) uint8 level: 仅 支持设置为 0x01 ESP8266 作为 SSL client uint32 flash_sector: 设置密钥 esp_cert_private_key.bin 烧录到 Flash 的位置, 例例如, 传 入 0x7A, 则对应烧录到 Flash 0x7A000 请注意, 不不要覆盖了了代码或系统区域 true: 成功 false: 失败 espconn_secure_cert_req_disable 关闭 ESP8266 作为 SSL client 时的证书认证 Espressif 113! /!

130 ! 4. TCP/UDP 接 口 注意 证书认证, 默认关闭 bool espconn_secure_ca_disable (uint8 level) uint8 level: 仅 支持设置为 0x01 ESP8266 作为 SSL client true: 成功 false: 失败 espconn_secure_set_default_certificate 注意 设置 ESP8266 作为 SSL server 时的证书 ESP8266_NONOS_SDK/examples/IoT_Demo 中提供使 用示例例 本接 口必须在 espconn_secure_accept 之前调 用, 传 入证书信息 bool espconn_secure_set_default_certificate (const uint8_t* certificate, uint16_t length) const uint8_t* certificate: 证书指针 uint16_t length: 证书 长度 true: 成功 false: 失败 espconn_secure_set_default_private_key 注意 设置 ESP8266 作为 SSL server 时的密钥 ESP8266_NONOS_SDK/examples/IoT_Demo 中提供使 用示例例 本接 口必须在 espconn_secure_accept 之前调 用, 传 入密钥信息 bool espconn_secure_set_default_private_key (const uint8_t* key, uint16_t length) const uint8_t* key: 密钥指针 uint16_t length: 密钥 长度 true: 成功 false: 失败 Espressif 114! /!

131 ! 4. TCP/UDP 接 口 4.3. UDP 接 口 espconn_create 建 立 UDP 传输 注意请注意设置 remote_ip 和 remote_port, 请勿设置为 0 sin8 espconn_create(struct espconn *espconn) struct espconn *espconn: 对应 网络连接的结构体 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 UDP 连接 ESPCONN_MEM: 空间不不 足 ESPCONN_ISCONN: 连接已经建 立 espconn_sendto UDP 发包接 口 sin16 espconn_sendto(struct espconn *espconn, uint8 *psent, uint16 length) struct espconn *espconn: 对应 网络连接的结构体 uint8 *psent: 待发送的数据 uint16 length: 发送的数据 长度 0: 成功 其它 : 失败, 错误码 ESPCONN_ARG: 未找到 espconn 对应的 UDP 传输 ESPCONN_MEM: 空间不不 足 ESPCONN_IF:UDP 发包失败 espconn_igmp_join 注意 加 入多播组请在 ESP8266 Station 已连 入路路由的情况下调 用 sint8 espconn_igmp_join(ip_addr_t *host_ip, ip_addr_t *multicast_ip) ip_addr_t *host_ip: 主机 IP ip_addr_t *multicast_ip: 多播组 IP 0: 成功其它 : 失败, 错误码 ESPCONN_MEM: 空间不不 足 Espressif 115! /!

132 ! 4. TCP/UDP 接 口 espconn_igmp_leave 退出多播组 sint8 espconn_igmp_leave(ip_addr_t *host_ip, ip_addr_t *multicast_ip) ip_addr_t *host_ip: 主机 IP ip_addr_t *multicast_ip: 多播组 IP 0: 成功其它 : 失败, 错误码 ESPCONN_MEM: 空间不不 足 espconn_dns_setserver 注意 设置默认 DNS server 本接 口必须在 ESP8266 DHCP client 关闭 wifi_station_dhcpc_stop 的情况下使 用 void espconn_dns_setserver(uint8 numdns, ip_addr_t *dnsserver) uint8 numdns:dns server ID, 支持设置两个 DNS server,id 分别为 0 和 1 ip_addr_t *dnsserver:dns server IP espconn_dns_getserver 查询 DNS server IP ip_addr_t espconn_dns_getserver(uint8 numdns) uint8 numdns:dns server ID, 支持传 入 0 或 1 DNS server IP Espressif 116! /!

133 ! 4. TCP/UDP 接 口 4.4. mdns 接 口 espconn_mdns_init mdns 初始化 若为 SoftAP+Station 模式, 请先调 用 wifi_set_broadcast_if(stationap_mode); 注意结构体 若使 用 ESP8266 Station 接 口, 请获得 IP 后, 再调 用本接 口初始化 mdns txt_data 必须为 key = value 的形式 struct mdns_info{ char *host_name; char *server_name; uint16 server_port; unsigned long ipaddr; char *txt_data[10]; }; void espconn_mdns_init(struct mdns_info *info) struct mdns_info *info:mdns 结构体 espconn_mdns_close 关闭 mdns, 对应开启 mdns 的 API:espconn_mdns_init void espconn_mdns_close(void) espconn_mdns_server_register 注册 mdns 服务器器 void espconn_mdns_server_register(void) Espressif 117! /!

134 ! 4. TCP/UDP 接 口 espconn_mdns_server_unregister 注销 mdns 服务器器 void espconn_mdns_server_unregister(void) espconn_mdns_get_servername 查询 mdns 服务器器名称 char* espconn_mdns_get_servername(void) 服务器器名称 espconn_mdns_set_servername 设置 mdns 服务器器名称 void espconn_mdns_set_servername(const char *name) const char *name: 服务器器名称 espconn_mdns_set_hostname 设置 mdns 主机名称 void espconn_mdns_set_hostname(char *name) char *name: 主机名称 espconn_mdns_get_hostname 查询 mdns 主机名称 char* espconn_mdns_get_hostname(void) 主机名称 Espressif 118! /!

135 ! 4. TCP/UDP 接 口 espconn_mdns_disable 去能 mdns, 对应使能 API:espconn_mdns_enable void espconn_mdns_disable(void) espconn_mdns_enable 使能 mdns void espconn_mdns_enable(void) mdns 示例例 定义 mdns 信息时, 请注意 host_name 和 server_name 不不能包含特殊字符 ( 例例如. 符 号 ), 或者协议名称 ( 例例如不不能定义为 http ) struct mdns_info info; void user_mdns_config() { struct ip_info ipconfig; wifi_get_ip_info(station_if, &ipconfig); info->host_name = espressif ; info->ipaddr = ipconfig.ip.addr; //ESP8266 station IP info->server_name = iot ; info->server_port = 8080; info->txt_data[0] = version = now ; info->txt_data[1] = user1 = data1 ; info->txt_data[2] = user2 = data2 ; espconn_mdns_init(&info); } Espressif 119! /!

136 ! 5. 应 用相关接 口 5. 应 用相关接 口 5.1. AT 接 口 AT 接 口位于 /ESP8266_NONOS_SDK/include/at_custom.h AT 接 口的使 用示例例, 请参考 ESP8266_NONOS_SDK/examples/at/user/user_main.c at_response_ok AT 串串 口 (UART0) 输出 OK void at_response_ok(void) at_response_error AT 串串 口 (UART0) 输出 ERROR void at_response_error(void) at_cmd_array_regist 示例例 注册 用户 自定义的 AT 指令 请仅调 用 一次, 将所有 用户 自定义 AT 指令 一并注册 void at_cmd_array_regist ( at_function * custom_at_cmd_arrar, uint32 cmd_num ) at_function * custom_at_cmd_arrar: 用户 自定义的 AT 指令数组 uint32 cmd_num: 用户 自定义的 AT 指令数 目 请参考 ESP8266_NONOS_SDK/examples/at/user/user_main.c Espressif 120! /!

137 ! 5. 应 用相关接 口 at_get_next_int_dec 从 AT 指令 行行中解析 int 型数字 bool at_get_next_int_dec (char **p_src,int* result,int* err) char **p_src: *p_src 为接收到的 AT 指令字符串串 int* result: 从 AT 指令中解析出的 int 型数字 int* err: 解析处理理时的错误码 - 1: 数字省略略时, 错误码 1-3: 只发现 - 时, 错误码 3 true: 正常解析到数字 ( 数字省略略时, 仍然 true, 但错误码会为 1); 示例例 false: 解析异常, 错误码 ; 异常可能 : 数字超过 10 bytes, 遇到 \r 结束符, 只发现 - 字 符 请参考 ESP8266_NONOS_SDK/examples/at/user/user_main.c at_data_str_copy 从 AT 指令 行行中解析字符串串 int32 at_data_str_copy (char * p_dest, char ** p_src,int32 max_len) char * p_dest: 从 AT 指令 行行中解析到的字符串串 char **p_src: *p_src 为接收到的 AT 指令字符串串 int32 max_len: 允许的最 大字符串串 长度 解析到的字符串串 长度 : >=0: 成功, 则解析到的字符串串 长度 <0: 失败, -1 示例例 请参考 ESP8266_NONOS_SDK/examples/at/user/user_main.c at_init 示例例 AT 初始化 void at_init (void) 请参考 ESP8266_NONOS_SDK/examples/at/user/user_main.c Espressif 121! /!

138 ! 5. 应 用相关接 口 at_port_print 示例例 从 AT 串串 口 (UART0) 输出字符串串 void at_port_print(const char *str) const char *str: 字符串串请参考 ESP8266_NONOS_SDK/examples/at/user/user_main.c at_set_custom_info 开发者 自定义 AT 版本信息, 可由指令 AT+GMR 查询到 void at_set_custom_info (char *info) char *info: 版本信息 at_enter_special_state 进 入 AT 指令执 行行态, 此时不不响应其他 AT 指令, busy void at_enter_special_state (void) at_leave_special_state 退出 AT 指令执 行行态 void at_leave_special_state (void) at_get_version 查询乐鑫提供的 AT lib 版本号 uint32 at_get_version (void) 乐鑫 AT lib 版本号 Espressif 122! /!

139 ! 5. 应 用相关接 口 at_register_uart_rx_intr 注意示例例 设置 UART0 RX 是由 用户使 用, 还是由 AT 使 用 本接 口可以重复调 用 运 行行 AT BIN,UART0 RX 默认供 AT 使 用 void at_register_uart_rx_intr (at_custom_uart_rx_intr rx_func) at_custom_uart_rx_intr: 注册 用户使 用 UART0 的 Rx 中断处理理函数 ; 如果传 NULL, 则切换 为 AT 使 用 UART0 void user_uart_rx_intr (uint8* data, int32 len) { } // UART0 rx for user os_printf( len=%d \r\n,len); os_printf(data); // change UART0 for AT at_register_uart_rx_intr(null); void user_init(void) { } at_register_uart_rx_intr(user_uart_rx_intr); at_response 设置 AT 响应 默认情况下,at_response 从 UART0 TX 输出, 与 at_port_print 相同 注意 如果调 用了了 at_register_response_func,at_response 的字符串串成为 response_func 的, 由 用户 自 行行处理理 void at_response (const char *str) const char *str: 字符串串 at_register_response_func 注册 at_response 的回调函数 调 用了了 at_register_response_func,at_response 的字符串串将传 入 response_func, 由 用户 自 行行处理理 void at_register_response_func (at_custom_response_func_type response_func) at_custom_response_func_type:at_response 的回调函数 Espressif 123! /!

140 ! 5. 应 用相关接 口 at_fake_uart_enable 使能模拟 UART, 开发者可 用于实现 网络 AT 指令, 或者 SDIO AT 指令 bool at_fake_uart_enable(bool enable, at_fake_uart_tx_func_type func) bool enable: 使能模拟 UART at_fake_uart_tx_func_type func: 模拟 UART Tx 的回调函数 true: 成功 false: 失败 at_fake_uart_rx 模拟 UART RX, 开发者可 用于实现 网络 AT 指令, 或者 SDIO AT 指令 uint32 at_fake_uart_rx(uint8* data, uint32 length) uint8* data: 模拟 UART Rx 收到的数据 uint32 length: 数据 长度如果执 行行成功, 则值与 length 相同 ; 否则, 执 行行失败 at_set_escape_character 设置 AT 指令的转义字符, 支持设置为符号! # & \ 的其中之 一, 默认转义字符为 \ bool at_set_escape_character(uint8 ch) uint8 ch: 转义字符, 支持传 入符号! # & \ 的其中之 一 true: 成功 false: 失败 Espressif 124! /!

141 ! 5. 应 用相关接 口 5.2. JSON 接 口 位于 ESP8266_NONOS_SDK/include/json/jsonparse.h & jsontree.h jsonparse_setup JSON 解析初始化 void jsonparse_setup( struct jsonparse_state *state, const char *json, int len ) struct jsonparse_state *state:json 解析指针 const char *json:json 解析字符串串 int len: 字符串串 长度 jsonparse_next 解析 JSON 格式下 一个元素 int jsonparse_next(struct jsonparse_state *state) struct jsonparse_state *state:json 解析指针 int: 解析结果 jsonparse_copy_value 复制当前解析字符串串到指定缓存 int jsonparse_copy_value( struct jsonparse_state *state, char *str, int size ) struct jsonparse_state *state:json 解析指针 char *str: 缓存指针 int size: 缓存 大 小 int: 复制结果 jsonparse_get_value_as_int 解析 JSON 格式为整型数据 int jsonparse_get_value_as_int(struct jsonparse_state *state) struct jsonparse_state *state:json 解析指针 Espressif 125! /!

142 ! 5. 应 用相关接 口 int: 解析结果 jsonparse_get_value_as_long 解析 JSON 格式为为 长整型数据 long jsonparse_get_value_as_long(struct jsonparse_state *state) struct jsonparse_state *state:json 解析指针 int: 解析结果 jsonparse_get_len 解析 JSON 格式数据 长度 int jsonparse_get_value_len(struct jsonparse_state *state) struct jsonparse_state *state:json 解析指针 int: 解析 长度 jsonparse_get_value_as_type 解析 JSON 格式数据类型 int jsonparse_get_value_as_type(struct jsonparse_state *state) struct jsonparse_state *state:json 解析指针 int:json 格式数据类型 jsonparse_strcmp_value 比较解析 JSON 数据与特定字符串串 int jsonparse_strcmp_value(struct jsonparse_state *state, const char *str) struct jsonparse_state *state:json 解析指针 const char *str: 字符串串缓存 int: 比较结果 jsontree_set_up 生成 JSON 格式数据树 void jsontree_setup( struct jsontree_context *js_ctx, struct jsontree_value *root, int (* putchar)(int) ) Espressif 126! /!

143 ! 5. 应 用相关接 口 struct jsontree_context *js_ctx:json 格式树元素指针 struct jsontree_value *root: 根树元素指针 int (* putchar)(int): 输 入函数 jsontree_reset 设置 JSON 数 void jsontree_reset(struct jsontree_context *js_ctx) struct jsontree_context *js_ctx:json 格式树指针 jsontree_path_name 获取 JSON 树 const char *jsontree_path_name( const struct jsontree_cotext *js_ctx, int depth ) struct jsontree_context *js_ctx:json 格式树指针 int depth:json 格式树深度 char*: 指针 jsontree_write_int 整型数写 入 JSON 树 void jsontree_write_int( const struct jsontree_context *js_ctx, int value ) struct jsontree_context *js_ctx:json 树指针 int value: 整型数 Espressif 127! /!

144 ! 5. 应 用相关接 口 jsontree_write_int_array 整型数组写 入 JSON 树 void jsontree_write_int_array( const struct jsontree_context *js_ctx, const int *text, uint32 length ) struct jsontree_context *js_ctx:json 树指针 int *text: 数组 入 口地址 uint32 length: 数组 长度 jsontree_write_string 字符串串写 入 JSON 树 void jsontree_write_string( const struct jsontree_context *js_ctx, const char *text ) struct jsontree_context *js_ctx:json 格式树指针 const char* text: 字符串串指针 jsontree_print_next 获取 JSON 树下 一个元素 int jsontree_print_next(struct jsontree_context *js_ctx) struct jsontree_context *js_ctx:json 树指针 int:json 树深度 jsontree_find_next 查找 JSON 树元素 struct jsontree_value *jsontree_find_next( struct jsontree_context *js_ctx, int type ) struct jsontree_context *js_ctx:json 树指针 int: 类型 struct jsontree_value *:JSON 树元素指针 Espressif 128! /!

145 ! 6. 结构体和宏定义 6. 结构体和宏定义 6.1. 定时器器 6.2. Wi-Fi Station typedef void ETSTimerFunc(void *timer_arg); typedef struct _ETSTIMER_ { struct _ETSTIMER_ *timer_next; uint32_t timer_expire; uint32_t timer_period; ETSTimerFunc *timer_func; void *timer_arg; } ETSTimer; typedef struct { int8 rssi; AUTH_MODE authmode; } wifi_fast_scan_threshold_t; struct station_config { uint8 ssid[32]; uint8 password[64]; uint8 bssid_set; // Note: If bssid_set is 1, station will just connect to the router // with both ssid[] and bssid[] matched. Please check about this. uint8 bssid[6]; wifi_fast_scan_threshold_t threshold; }; 注意 : BSSID 表示 AP 的 MAC 地址, 用于多个 AP 的 SSID 相同的情况 如果 station_config.bssid_set==1, station_config.bssid 必须设置, 否则连接失败 一般情况下,station_config.bssid_set 设置为 SoftAP typedef enum _auth_mode { AUTH_OPEN = 0, AUTH_WEP, AUTH_WPA_PSK, AUTH_WPA2_PSK, AUTH_WPA_WPA2_PSK } AUTH_MODE; Espressif 129! /!

146 ! 6. 结构体和宏定义 struct softap_config { uint8 ssid[32]; uint8 password[64]; uint8 ssid_len; uint8 channel; // support 1 ~ 13 uint8 authmode; // Don t support AUTH_WEP in soft-ap mode uint8 ssid_hidden; // default 0 uint8 max_connection; // default 4, max 4 uint16 beacon_interval; // 100 ~ ms, default 100 }; 注意 : 如果 softap_config.ssid_len==0, 读取 SSID 直 至结束符, 否则, 根据 softap_config.ssid_len 设置 SSID 的 长度 Scan struct scan_config { uint8 *ssid; uint8 *bssid; uint8 channel; uint8 show_hidden; // Scan APs which are hiding their SSID or not. wifi_scan_type_t scan_type; // scan type, active or passive wifi_scan_time_t scan_time; // scan time per channel }; struct bss_info { STAILQ_ENTRY(bss_info) next; uint8 bssid[6]; uint8 ssid[32]; uint8 ssid_len; uint8 channel; sint8 rssi; AUTH_MODE authmode; uint8 is_hidden; // SSID of current AP is hidden or not sint16 freq_offset; // AP s frequency offset sint16 freqcal_val; uint8 *esp_mesh_ie; uint8 simple_pair; CIPHER_TYPE pairwise_cipher; CIPHER_TYPE group_cipher; uint32_t phy_11b:1; uint32_t phy_11g:1; uint32_t phy_11n:1; uint32_t wps:1; uint32_t reserved:28; }; typedef void (* scan_done_cb_t)(void *arg, STATUS status); Espressif 130! /!

147 ! 6. 结构体和宏定义 Wi-Fi Event 结构体 enum { EVENT_STAMODE_CONNECTED = 0, EVENT_STAMODE_DISCONNECTED, EVENT_STAMODE_AUTHMODE_CHANGE, EVENT_STAMODE_GOT_IP, EVENT_STAMODE_DHCP_TIMEOUT, EVENT_SOFTAPMODE_STACONNECTED, EVENT_SOFTAPMODE_STADISCONNECTED, EVENT_SOFTAPMODE_PROBEREQRECVED, EVENT_OPMODE_CHANGED, EVENT_SOFTAPMODE_DISTRIBUTE_STA_IP, EVENT_MAX }; enum { REASON_UNSPECIFIED = 1, REASON_AUTH_EXPIRE = 2, REASON_AUTH_LEAVE = 3, REASON_ASSOC_EXPIRE = 4, REASON_ASSOC_TOOMANY = 5, REASON_NOT_AUTHED = 6, REASON_NOT_ASSOCED = 7, REASON_ASSOC_LEAVE = 8, REASON_ASSOC_NOT_AUTHED = 9, REASON_DISASSOC_PWRCAP_BAD = 10, /* 11h */ REASON_DISASSOC_SUPCHAN_BAD = 11, /* 11h */ REASON_IE_INVALID = 13, /* 11i */ REASON_MIC_FAILURE = 14, /* 11i */ REASON_4WAY_HANDSHAKE_TIMEOUT = 15, /* 11i */ REASON_GROUP_KEY_UPDATE_TIMEOUT = 16, /* 11i */ REASON_IE_IN_4WAY_DIFFERS = 17, /* 11i */ REASON_GROUP_CIPHER_INVALID = 18, /* 11i */ REASON_PAIRWISE_CIPHER_INVALID = 19, /* 11i */ REASON_AKMP_INVALID = 20, /* 11i */ REASON_UNSUPP_RSN_IE_VERSION = 21, /* 11i */ REASON_INVALID_RSN_IE_CAP = 22, /* 11i */ REASON_802_1X_AUTH_FAILED = 23, /* 11i */ REASON_CIPHER_SUITE_REJECTED = 24, /* 11i */ }; REASON_BEACON_TIMEOUT = 200, REASON_NO_AP_FOUND = 201, REASON_AUTH_FAIL = 202, REASON_ASSOC_FAIL = 203, REASON_HANDSHAKE_TIMEOUT = 204, typedef struct { uint8 ssid[32]; uint8 ssid_len; Espressif 131! /!

148 ! 6. 结构体和宏定义 uint8 bssid[6]; uint8 channel; } Event_StaMode_Connected_t; typedef struct { uint8 ssid[32]; uint8 ssid_len; uint8 bssid[6]; uint8 reason; } Event_StaMode_Disconnected_t; typedef struct { uint8 old_mode; uint8 new_mode; } Event_StaMode_AuthMode_Change_t; typedef struct { struct ip_addr ip; struct ip_addr mask; struct ip_addr gw; } Event_StaMode_Got_IP_t; typedef struct { uint8 mac[6]; uint8 aid; } Event_SoftAPMode_StaConnected_t; typedef struct { uint8 mac[6]; struct ip_addr ip; uint8 aid; } Event_SoftAPMode_Distribute_Sta_IP_t; typedef struct { uint8 mac[6]; uint8 aid; } Event_SoftAPMode_StaDisconnected_t; typedef struct { int rssi; uint8 mac[6]; } Event_SoftAPMode_ProbeReqRecved_t; typedef struct { uint8 old_opmode; uint8 new_opmode; } Event_OpMode_Change_t; typedef union { Event_StaMode_Connected_t connected; Espressif 132! /!

149 ! 6. 结构体和宏定义 Event_StaMode_Disconnected_t Event_StaMode_AuthMode_Change_t Event_StaMode_Got_IP_t Event_SoftAPMode_StaConnected_t Event_SoftAPMode_Distribute_Sta_IP_t Event_SoftAPMode_StaDisconnected_t Event_SoftAPMode_ProbeReqRecved_t Event_OpMode_Change_t } Event_Info_u; disconnected; auth_change; got_ip; sta_connected; distribute_sta_ip; sta_disconnected; ap_probereqrecved; opmode_changed; typedef struct _esp_event { uint32 event; Event_Info_u event_info; } System_Event_t; SmartConfig 结构体 typedef enum { SC_STATUS_WAIT = 0, // 连接未开始, 请勿在此阶段开始连接 SC_STATUS_FIND_CHANNEL, // 请在此阶段开启 APP 进行配对连接 SC_STATUS_GETTING_SSID_PSWD, SC_STATUS_LINK, SC_STATUS_LINK_OVER, } sc_status; typedef enum { SC_TYPE_ESPTOUCH = 0, SC_TYPE_AIRKISS, SC_TYPE_ESPTOUCH_AIRKISS, } sc_type; // 获取到 IP, 连接路由完成 6.3. JSON 相关结构体 JSON 结构体 struct jsontree_value { uint8_t type; }; struct jsontree_pair { const char *name; struct jsontree_value *value; }; struct jsontree_context { struct jsontree_value *values[jsontree_max_depth]; uint16_t index[jsontree_max_depth]; int (* putchar)(int); uint8_t depth; Espressif 133! /!

150 ! 6. 结构体和宏定义 uint8_t path; int callback_state; }; struct jsontree_callback { uint8_t type; int (* output)(struct jsontree_context *js_ctx); int (* set)(struct jsontree_context *js_ctx, struct jsonparse_state *parser); }; struct jsontree_object { uint8_t type; uint8_t count; struct jsontree_pair *pairs; }; struct jsontree_array { uint8_t type; uint8_t count; struct jsontree_value **values; }; JSON 宏定义 struct jsonparse_state { const char *json; int pos; int len; int depth; int vstart; int vlen; char vtype; char error; char stack[jsonparse_max_depth]; }; #define JSONTREE_OBJECT(name,...) / static struct jsontree_pair jsontree_pair_##name[] = { VA_ARGS }; / static struct jsontree_object name = { / JSON_TYPE_OBJECT, / sizeof(jsontree_pair_##name)/sizeof(struct jsontree_pair), / jsontree_pair_##name } #define JSONTREE_PAIR_ARRAY(value) (struct jsontree_value *)(value) #define JSONTREE_ARRAY(name,...) / static struct jsontree_value* jsontree_value_##name[] = { VA_ARGS }; / static struct jsontree_array name = { / JSON_TYPE_ARRAY, / sizeof(jsontree_value_##name)/sizeof(struct jsontree_value*), / jsontree_value_##name } Espressif 134! /!

151 ! 6. 结构体和宏定义 6.4. espconn 回调函数 espconn /** callback prototype to inform about events for a espconn */ typedef void (* espconn_recv_callback)(void *arg, char *pdata, unsigned short len); typedef void (* espconn_callback)(void *arg, char *pdata, unsigned short len); typedef void (* espconn_connect_callback)(void *arg); typedef void* espconn_handle; typedef struct _esp_tcp { int remote_port; int local_port; uint8 local_ip[4]; uint8 remote_ip[4]; espconn_connect_callback connect_callback; espconn_reconnect_callback reconnect_callback; espconn_connect_callback disconnect_callback; espconn_connect_callback write_finish_fn; } esp_tcp; typedef struct _esp_udp { int remote_port; int local_port; uint8 local_ip[4]; uint8 remote_ip[4]; } esp_udp; /** Protocol family and type of the espconn */ enum espconn_type { ESPCONN_INVALID = 0, /* ESPCONN_TCP Group */ ESPCONN_TCP = 0x10, /* ESPCONN_UDP Group */ ESPCONN_UDP = 0x20, }; enum espconn_option{ ESPCONN_START = 0x00, ESPCONN_REUSEADDR = 0x01, ESPCONN_NODELAY = 0x02, ESPCONN_COPY = 0x04, ESPCONN_KEEPALIVE = 0x08, ESPCONN_MANUALRECV = 0x10, ESPCONN_END } enum espconn_level{ ESPCONN_KEEPIDLE, Espressif 135! /!

152 ! 6. 结构体和宏定义 } ESPCONN_KEEPINTVL, ESPCONN_KEEPCNT /** Current state of the espconn. Non-TCP espconn are always in state ESPCONN_NONE! */ enum espconn_state { ESPCONN_NONE, ESPCONN_WAIT, ESPCONN_LISTEN, ESPCONN_CONNECT, ESPCONN_WRITE, ESPCONN_READ, ESPCONN_CLOSE }; /** A espconn descriptor */ struct espconn { /** type of the espconn (TCP, UDP) */ enum espconn_type type; /** current state of the espconn */ enum espconn_state state; union { esp_tcp *tcp; esp_udp *udp; } proto; /** A callback function that is informed about events for this espconn */ espconn_recv_callback recv_callback; espconn_sent_callback sent_callback; uint8 link_cnt; void *reverse; // reversed for customer use }; 6.5. 中断相关宏定义 /* interrupt related */ #define ETS_SPI_INUM 2 #define ETS_GPIO_INUM 4 #define ETS_UART_INUM 5 #define ETS_UART1_INUM 5 #define ETS_FRC_TIMER1_INUM 9 /* disable all interrupts */ #define ETS_INTR_LOCK() /* enable all interrupts */ #define ETS_INTR_UNLOCK() ets_intr_lock() ets_intr_unlock() /* register interrupt handler of frc timer1 */ #define ETS_FRC_TIMER1_INTR_ATTACH(func, arg) \ ets_isr_attach(ets_frc_timer1_inum, (func), (void *)(arg)) Espressif 136! /!

153 ! 6. 结构体和宏定义 /* register interrupt handler of GPIO */ #define ETS_GPIO_INTR_ATTACH(func, arg) \ ets_isr_attach(ets_gpio_inum, (func), (void *)(arg)) /* register interrupt handler of UART */ #define ETS_UART_INTR_ATTACH(func, arg) \ ets_isr_attach(ets_uart_inum, (func), (void *)(arg)) /* register interrupt handler of SPI */ #define ETS_SPI_INTR_ATTACH(func, arg) \ ets_isr_attach(ets_spi_inum, (func), (void *)(arg)) /* enable a interrupt */ #define ETS_INTR_ENABLE(inum) ets_isr_unmask((1<<inum)) /* disable a interrupt */ #define ETS_INTR_DISABLE(inum) ets_isr_mask((1<<inum)) /* enable SPI interrupt */ #define ETS_SPI_INTR_ENABLE() ETS_INTR_ENABLE(ETS_SPI_INUM) /* enable UART interrupt */ #define ETS_UART_INTR_ENABLE() ETS_INTR_ENABLE(ETS_UART_INUM) /* disable UART interrupt */ #define ETS_UART_INTR_DISABLE() ETS_INTR_DISABLE(ETS_UART_INUM) /* enable frc1 timer interrupt */ #define ETS_FRC1_INTR_ENABLE() ETS_INTR_ENABLE(ETS_FRC_TIMER1_INUM) /* disable frc1 timer interrupt */ #define ETS_FRC1_INTR_DISABLE() ETS_INTR_DISABLE(ETS_FRC_TIMER1_INUM) /* enable GPIO interrupt */ #define ETS_GPIO_INTR_ENABLE() ETS_INTR_ENABLE(ETS_GPIO_INUM) /* disable GPIO interrupt */ #define ETS_GPIO_INTR_DISABLE() ETS_INTR_DISABLE(ETS_GPIO_INUM) Espressif 137! /!

154 ! 7. 外设驱动接 口 7. 外设驱动接 口 7.1. GPIO 接 口 外围设备驱动可以参考 /ESP8266_NONOS_SDK/driver_lib GPIO 相关接 口位于 /ESP8266_NONOS_SDK/include/eagle_soc.h & gpio.h 使 用示例例可参考 /ESP8266_NONOS_SDK/examples/IoT_Demo/user/user_plug.c PIN 相关宏定义以下宏定义控制 GPIO 管脚状态 : PIN_PULLUP_DIS(PIN_NAME) 管脚上拉屏蔽示例例 : PIN_PULLUP_EN(PIN_NAME) PIN_FUNC_SELECT(PIN_NAME, FUNC) 管脚上拉使能 管脚选择 // Use MTDI pin as GPIO12. PIN_FUNC_SELECT(PERIPHS_IO_MUX_MTDI_U, FUNC_GPIO12); gpio_output_set 设置 GPIO 属性 void gpio_output_set( uint32 set_mask, uint32 clear_mask, uint32 enable_mask, uint32 disable_mask ) uint32 set_mask: 设置输出为 高的位, 对应位为 1, 输出 高, 对应位为 0, 不不改变状态 uint32 clear_mask: 设置输出为低的位, 对应位为 1, 输出低, 对应位为 0, 不不改变状态 uint32 enable_mask: 设置使能输出的位 uint32 disable_mask: 设置使能输 入的位 gpio_output_set(bit12, 0, BIT12, 0): 设置 GPIO12 输出 高电平 ; gpio_output_set(0, BIT12, BIT12, 0): 设置 GPIO12 输出低电平 ; 示例例 gpio_output_set(bit12, BIT13, BIT12 BIT13, 0): 设置 GPIO12 输出 高电平, GPIO13 输 出低电平 ; gpio_output_set(0, 0, 0, BIT12): 设置 GPIO12 为输 入 Espressif 138! /!

155 ! 7. 外设驱动接 口 GPIO 输 入输出相关宏 GPIO_OUTPUT_SET(gpio_no, bit_value) GPIO_DIS_OUTPUT(gpio_no) GPIO_INPUT_GET(gpio_no) 设置 gpio_no 管脚输出 bit_value, 与上 一节的输出 高低电平的示例例相同 设置 gpio_no 管脚输 入, 与上 一节的设置输 入示例例相同 获取 gpio_no 管脚的电平状态 GPIO 中断 ETS_GPIO_INTR_ATTACH(func, arg) ETS_GPIO_INTR_DISABLE() ETS_GPIO_INTR_ENABLE() 注册 GPIO 中断处理理函数 关 GPIO 中断 开 GPIO 中断 gpio_pin_intr_state_set 设置 GPIO 中断触发状态 void gpio_pin_intr_state_set( uint32 i, GPIO_INT_TYPE intr_state ) uint32 i:gpio pin ID, 例例如设置 GPIO14, 则为 GPIO_ID_PIN(14); GPIO_INT_TYPE intr_state : 中断触发状态 : typedef enum { GPIO_PIN_INTR_DISABLE = 0, GPIO_PIN_INTR_POSEDGE = 1, GPIO_PIN_INTR_NEGEDGE = 2, GPIO_PIN_INTR_ANYEDGE = 3, GPIO_PIN_INTR_LOLEVEL = 4, GPIO_PIN_INTR_HILEVEL = 5 } GPIO_INT_TYPE; GPIO 中断处理理函数 在 GPIO 中断处理理函数内, 需要做如下操作来清除响应位的中断状态 : uint32 gpio_status; gpio_status = GPIO_REG_READ(GPIO_STATUS_ADDRESS); //clear interrupt status GPIO_REG_WRITE(GPIO_STATUS_W1TC_ADDRESS, gpio_status); Espressif 139! /!

156 ! 7. 外设驱动接 口 7.2. UART 接 口 默认情况下,UART0 作为系统的打印信息输出接 口, 当配置为双 UART 时,UART0 作为数据收发接 口,UART1 作为打印信息输出接 口 使 用时, 请确保硬件连接正确 关于 UART 的详细介绍, 请参考 ESP8266 技术参考 uart_init 波特率 双 UART 模式, 两个 UART 波特率初始化 void uart_init( UartBautRate uart0_br, UartBautRate uart1_br ) UartBautRate uart0_br:uart0 波特率 UartBautRate uart1_br:uart1 波特率 typedef enum { BIT_RATE_9600 = 9600, BIT_RATE_19200 = 19200, BIT_RATE_38400 = 38400, BIT_RATE_57600 = 57600, BIT_RATE_74880 = 74880, BIT_RATE_ = , BIT_RATE_ = , BIT_RATE_ = , BIT_RATE_ = } UartBautRate; uart0_tx_buffer 通过 UART0 输出 用户数据 void uart0_tx_buffer(uint8 *buf, uint16 len) uint8 *buf: 数据缓存 uint16 len: 数据 长度 uart0_rx_intr_handler UART0 中断处理理函数, 用户可在该函数内添加对接收到数据包的处理理 void uart0_rx_intr_handler(void *para) void *para: 指向数据结构 RcvMsgBuff 的指针 Espressif 140! /!

157 ! 7. 外设驱动接 口 uart_div_modify 示例例 设置 UART 波特率 void uart_div_modify(uint8 uart_no, uint32 DivLatchValue) uint8 uart_no:uart 号,UART0 或者 UART1 uint32 DivLatchValue: 分频 void ICACHE_FLASH_ATTR UART_SetBaudrate(uint8 uart_no, uint32 baud_rate) { uart_div_modify(uart_no, UART_CLK_FREQ /baud_rate); } 7.3. I2C Master 接 口 ESP8266 不不能作为 I2C 从设备, 但可以作为 I2C 主设备, 对其他 I2C 从设备 ( 例例如 大多数数字传感器器 ) 进 行行控制与读写 每个 GPIO 管脚内部都可以配置为开漏漏模式 (open-drain), 从 而可以灵活的将 GPIO 口 用作 I2C data 或 clock 同时, 芯 片内部提供上拉电阻, 以节省外部的上拉电阻 关于 I2C 的详细介绍, 请参考 ESP8266 技术参考 i2c_master_gpio_init 设置 GPIO 为 I2C master 模式 void i2c_master_gpio_init (void) i2c_master_init 初始化 I2C void i2c_master_init(void) Espressif 141! /!

158 ! 7. 外设驱动接 口 i2c_master_start 设置 I2C 进 入发送状态 void i2c_master_start(void) i2c_master_stop 设置 I2C 停 止发送 void i2c_master_stop(void) i2c_master_send_ack 发送 I2C ACK void i2c_master_send_ack (void) i2c_master_send_nack 发送 I2C NACK void i2c_master_send_nack (void) i2c_master_checkack 检查 I2C slave 的 ACK bool i2c_master_checkack (void) true: 获取 I2C slave ACK false: 获取 I2C slave NACK Espressif 142! /!

159 ! 7. 外设驱动接 口 i2c_master_readbyte 从 I2C slave 读取 一个字节 uint8 i2c_master_readbyte (void) uint8: 读取到的值 i2c_master_writebyte 向 I2C slave 写 一个字节 void i2c_master_writebyte (uint8 wrdata) uint8 wrdata: 数据 7.4. PWM 接 口 本 文档仅简单介绍 pwm.h 中的 PWM 相关接 口, 详细的 PWM 介绍 文档请参考 ESP8266 技术参考 PWM 驱动接 口函数不不能跟 hw_timer.c 的接 口同时使 用, 因为它们共 用了了同 一个硬件定时器器 PWM 不不 支持进 入 Deep sleep 模式, 也请勿调 用 wifi_set_sleep_type(ligt_sleep); 将 自动睡眠模式设置为 Light-sleep 因为 Lightsleep 在睡眠期间会停 CPU, 停 CPU 期间不不能响应 NMI 中断 pwm_init 初始化 PWM, 包括 GPIO 选择, 周期和占空 比 目前仅 支持调 用 一次 void pwm_init( uint32 period, uint8 *duty, uint32 pwm_channel_num, uint32 (*pin_info_list)[3]) uint32 period:pwm 周期 uint8 *duty: 各路路 PWM 的占空 比 uint32 pwm_channel_num:pwm 通道数 uint32 (*pin_info_list)[3]:pwm 各通道的 GPIO 硬件 本是 一个 n * 3 的数组指 针, 数组中定义了了 GPIO 的寄存器器, 对应 PIN 脚的 IO 复 用值和 GPIO 对应的序号 Espressif 143! /!

160 ! 7. 外设驱动接 口 初始化 一个三通道的 PWM: uint32 io_info[][3] = 示例例 {{PWM_0_OUT_IO_MUX,PWM_0_OUT_IO_FUNC,PWM_0_OUT_IO_NUM}, {PWM_1_OUT_IO_MUX,PWM_1_OUT_IO_FUNC,PWM_1_OUT_IO_NUM}, {PWM_2_OUT_IO_MUX,PWM_2_OUT_IO_FUNC,PWM_2_OUT_IO_NUM}}; pwm_init(light_param.pwm_period, light_param.pwm_duty, 3, io_info); pwm_start PWM 开始 每次更更新 PWM 设置后, 都需要重新调 用本接 口进 行行计算 void pwm_start (void) pwm_set_duty 注意 设置 PWM 某个通道信号的占空 比 设置各路路 PWM 信号 高电平所占的时间,duty 的范围随 PWM 周期改变, 最 大值为 :Period * 1000 /45 例例如,1KHz PWM,duty 范围是 :0 ~ 设置完成后, 需要调 用 pwm_start 生效 void pwm_set_duty(uint32 duty, uint8 channel) uint32 duty: 设置 高电平时间, 占空 比的值为 (duty*45)/ (period*1000) uint8 channel: 当前要设置的 PWM 通道, 取值范围依据实际使 用了了 几路路 PWM, 在 IOT_Demo 中取值在 #define PWM_CHANNEL 定义的范围内 pwm_get_duty 获取某路路 PWM 信号的 duty, 占空 比的值为 (duty*45)/ (period*1000) uint8 pwm_get_duty(uint8 channel) uint8 channel: 当前要查询的 PWM 通道, 取值范围依据实际使 用了了 几路路 PWM, 在 IOT_Demo 中取值在 #define PWM_CHANNEL 定义的范围内 对应某路路 PWM 信号的 duty pwm_set_period 设置 PWM 周期, 单位 :μs 例例如,1KHz PWM, 为 1000 μs 注意 设置完成后, 需要调 用 pwm_start 生效 void pwm_set_period(uint32 period) uint32 period:pwm 周期, 单位 :μs Espressif 144! /!

161 ! 7. 外设驱动接 口 pwm_get_period 查询 PWM 周期 uint32 pwm_get_period(void) PWM 周期, 单位 :μs get_pwm_version 查询 PWM 版本信息 uint32 get_pwm_version(void) PWM 版本信息 7.5. SDIO 接 口 sdio_slave_init ESP8266 仅 支持作为 SDIO slave 初始化 SDIO void sdio_slave_init(void) sdio_load_data 加载数据到 SDIO buffer 中, 并通知 SDIO host 读取 int32 sdio_load_data(const uint8* data, uint32 len) const uint8* data: 待传输的数据 uint32 len: 数据 长度实际成功加载到 SDIO buffer 中的数据 长度 目前不不 支持加载部分数据, 如果数据超过 SDIO buffer 可加载容量量, 将 0, 数据加载失败 Espressif 145! /!

162 ! 7. 外设驱动接 口 sdio_register_recv_cb 回调 注册 SDIO 收到 host 数据的回调函数 typedef void(*sdio_recv_data_callback)(uint8* data, uint32 len) 注册的回调函数不不能放在 cache 中, 即回调函数前不不能添加 ICACHE_FLASH_ATTR 宏定义 bool sdio_register_recv_cb(sdio_recv_data_callback cb) sdio_recv_data_callback cb: 回调函数 true: 注册成功 false: 注册失败 Espressif 146! /!

163 ! 附录 A A. 附录 A.1. ESPCONN 编程 可参考乐鑫提供的示例例代码 : A.1.1. TCP Client 模式 注意 : ESP8266 工作在 Station 模式下, 需确认 ESP8266 已经连接 AP( 路路由 ) 分配到 IP 地址, 启 用 client 连接 ESP8266 工作在 SoftAP 模式下, 需确认连接 ESP8266 的设备已被分配到 IP 地址, 启 用 client 连接 步骤如下 : 1. 依据 工作协议初始化 espconn ; 2. 注册连接成功的回调函数和连接失败重连的回调函数 ; 调 用 espconn_regist_connectcb 和 espconn_regist_reconcb 3. 调 用 espconn_connect 建 立与 TCP Server 的连接 ; 4. TCP 连接建 立成功后, 在连接成功的回调函数 espconn_connect_callback 中, 注册接 收数据的回调函数, 发送数据成功的回调函数和断开连接的回调函数 调 用 espconn_regist_recvcb espconn_regist_sentcb 和 espconn_regist_disconcb 5. 在接收数据的回调函数, 或者发送数据成功的回调函数中, 执 行行断开连接操作时, 建 议适当延时 一定时间, 确保底层函数执 行行结束 A.1.2. TCP Server 模式 注意 : ESP8266 工作在 Station 模式下, 需确认 ESP8266 已经分配到 IP 地址, 再启 用 server 侦听 ESP8266 工作在 SoftAP 模式下, 可以直接启 用 server 侦听 步骤如下 : 1. 依据 工作协议初始化 espconn ; Espressif 147! /!

164 ! 附录 A 2. 注册连接成功的回调函数和连接失败重连的回调函数 ; 调 用 espconn_regist_connectcb 和 espconn_regist_reconcb 3. 调 用 espconn_accept 侦听 TCP 连接 ; 4. TCP 连接建 立成功后, 在连接成功的回调函数 espconn_connect_callback 中, 注册接 收数据的回调函数, 发送数据成功的回调函数和断开连接的回调函数 调 用 espconn_regist_recvcb espconn_regist_sentcb 和 espconn_regist_disconcb A.1.3. espconn Callback 注册函数 回调函数 说明 espconn_regist_connectcb espconn_connect_callback TCP 连接建 立成功 espconn_regist_reconcb espconn_reconnect_callback TCP 连接发 生异常 而断开 espconn_regist_sentcb espconn_sent_callback TCP 或 UDP 数据发送完成 espconn_regist_recvcb espconn_recv_callback TCP 或 UDP 数据接收 espconn_regist_write_finish espconn_write_finish_callback 数据成功写 入 TCP 数据缓存 espconn_regist_disconcb espconn_disconnect_callback TCP 连接正常断开 注意 : 回调函数中传 入的指针 arg, 对应 网络连接的结构体 espconn 指针 该指针为 SDK 内部维护的指针, 不不同回调传 入的指针地址可能不不 一样, 请勿依此判断 网络连接 可根据 espconn 结构体中的 remote_ip remote_port 判断多连接中的不不同 网络传输 如果 espconn_connect( 或者 espconn_secure_connect) 失败, 非零值, 连接未建 立, 不不会进 入任何 espconn callback 请勿在 espconn 任何回调中调 用 espconn_disconnect( 或者 espconn_secure_disconnect) 断开连接 如有需要, 可以在 espconn 回调中使 用触发任务的 方式 (system_os_task 和 system_os_post) 调 用 espconn_disconnect( 或者 espconn_secure_disconnect) 断开连接 A.2. RTC API 使 用示例例 以下测试示例例, 可以验证 RTC 时间和系统时间, 在 system_restart 时的变化, 以及读写 RTC memory #include "ets_sys.h" #include "osapi.h" #include "user_interface.h" os_timer_t rtc_test_t; #define RTC_MAGIC 0x55aaaa55 Espressif 148! /!

165 ! 附录 A typedef struct { uint64 time_acc; uint32 magic ; uint32 time_base; }RTC_TIMER_DEMO; void rtc_count() { RTC_TIMER_DEMO rtc_time; static uint8 cnt = 0; system_rtc_mem_read(64, &rtc_time, sizeof(rtc_time)); if(rtc_time.magic!=rtc_magic){ os_printf("rtc time init...\r\n"); rtc_time.magic = RTC_MAGIC; rtc_time.time_acc= 0; rtc_time.time_base = system_get_rtc_time(); os_printf("time base : %d \r\n",rtc_time.time_base); } os_printf("==================\r\n"); os_printf("rtc time test : \r\n"); uint32 rtc_t1,rtc_t2; uint32 st1,st2; uint32 cal1, cal2; rtc_t1 = system_get_rtc_time(); st1 = system_get_time(); cal1 = system_rtc_clock_cali_proc(); os_delay_us(300); st2 = system_get_time(); rtc_t2 = system_get_rtc_time(); cal2 = system_rtc_clock_cali_proc(); os_printf(" rtc_t2-t1 : %d \r\n",rtc_t2-rtc_t1); os_printf(" st2-t2 : %d \r\n",st2-st1); os_printf("cal 1 : %d.%d \r\n", ((cal1*1000)>>12)/1000, ((cal1*1000)>>12)%1000 ); os_printf("cal 2 : %d.%d \r\n",((cal2*1000)>>12)/1000,((cal2*1000)>>12)%1000 ); os_printf("==================\r\n\r\n"); rtc_time.time_acc += ( ((uint64)(rtc_t2 - rtc_time.time_base)) * ( (uint64) ((cal2*1000)>>12)) ) ; os_printf("rtc time acc : %lld \r\n",rtc_time.time_acc); os_printf("power on time : %lld us\r\n", rtc_time.time_acc/1000); os_printf("power on time : %lld.%02lld S\r\n", (rtc_time.time_acc/ )/100, (rtc_time.time_acc/ )%100); rtc_time.time_base = rtc_t2; Espressif 149! /!

166 ! 附录 A } system_rtc_mem_write(64, &rtc_time, sizeof(rtc_time)); os_printf(" \r\n"); if(5 == (cnt++)){ os_printf("system restart\r\n"); system_restart(); }else{ os_printf("continue...\r\n"); } void user_init(void) { rtc_count(); os_printf("sdk version:%s\n", system_get_sdk_version()); os_timer_disarm(&rtc_test_t); os_timer_setfn(&rtc_test_t,rtc_count,null); os_timer_arm(&rtc_test_t,10000,1); } A.3. Sniffer 说明 关于 sniffer 的详细说明, 请参考 ESP8266 技术参考 A.4. ESP8266 SoftAP 和 Station 信道定义 虽然 ESP8266 支持 SoftAP+Station 共存模式, 但是 ESP8266 实际只有 一个硬件信道 因此在 SoftAP+Station 模式时,ESP8266 SoftAP 会动态调整信道值与 ESP8266 Station 一致 这个限制会导致 ESP8266 SoftAP+Station 模式时 一些 行行为上的不不便便, 用户请注意 例例如 : 情况 一 1. 如果 ESP8266 Station 连接到 一个路路由 ( 假设路路由信道号为 6) 2. 通过接 口 wifi_softap_set_config 设置 ESP8266 SoftAP 3. 若设置值合法有效, 该 API 将 true, 但信道号仍然会 自动调节成与 ESP8266 Station 接 口 一致, 在这个例例 子 里里也就是信道号为 6 因为 ESP8266 在硬件上只有 一个信道, 由 ESP8266 Station 与 SoftAP 接 口共 用 情况 二 1. 调 用接 口 wifi_softap_set_config 设置 ESP8266 SoftAP( 例例如信道号为 5) 2. 其他 Station 连接到 ESP8266 SoftAP Espressif 150! /!

167 !! 附录 A 3. 将 ESP8266 Station 连接到路路由 ( 假设路路由信道号为 6) 4. ESP8266 SoftAP 将 自动调整信道号与 ESP8266 Station 一致 ( 信道 6) 5. 由于信道改变, 之前连接到 ESP8266 SoftAP 的 Station 的 Wi-Fi 连接断开 情况三 1. 其他 Station 与 ESP8266 SoftAP 建 立连接 2. 如果 ESP8266 Station 一直尝试扫描或连接某路路由, 可能导致 ESP8266 SoftAP 端的连接断开 3. 因为 ESP8266 Station 会遍历各个信道查找 目标路路由, 意味着 ESP8266 其实在不不停切换信道,ESP8266 SoftAP 的信道也因此在不不停更更改 这可能导致 ESP8266 SoftAP 端的原有连接断开 4. 这种情况, 用户可以通过设置定时器器, 超时后调 用 wifi_station_disconnect 停 止 ESP8266 Station 不不断连接路路由的尝试 ; 或者在初始配置时, 调 用 wifi_station_set_reconnect_policy 和 wifi_station_set_auto_connect 禁 止 ESP8266 Station 尝试重连路路由 A.5. ESP8266 启动信息说明 ESP8266 启动时, 将从 UART0 以波特率 打印如下启动信息 : 其中可供 用户参考的启动信息说明如下 : 启动信息 说明 1: 上电 rst cause 2: 外部复位 Espressif 151! /!