Kolban's Book on the ESP32 & ESP8266

Description

I've been working in the software business for over 30 years but until recently, hadn't been playing directly with Micro Processors. When I bought a Raspberry PI and then an Arduino, I'm afraid I got hooked. In my house I am surrounded by computers of all shapes, sizes and capacities … any one of them with orders of magnitude more power than any of these small devices … however, I still found myself fascinated. When I stumbled across the ESP8266 earlier this year, it piqued my interest. I hadn't touched C programming in decades (I'm a Java man these days). As I started to read what was available in the way of documentation from the excellent community surrounding the device, I found that there were only small pockets of knowledge. The best source of information was (and still is) the official PDFs for the SDK from Espressif (the makers of the ESP8266) but even that is quite "light" on examples and background. As I studied the device, I started to make notes and my pages of notes continued to grow and grow. This book is my collated and polished version of those notes. Rather than keep them to myself, I offer them to all of us in the ESP8266 community in the hope that they will be of some value. My plan is to continue to update this work as we all learn more and share what we find in the community forums. As such, I will re-release the work at regular intervals so please check back at the book's home page for the latest. Introduction Overview The ESP8266 Maturity The ESP8266 specification ESP8266 Modules ESP-12 ESP-1 Adafruit HUZZAH NodeMCU devKit node.IT (aka ESP-210) SparkFun WiFi Shield – ESP8266 Espresso Lite Wemos D1 Oak by digistump Connecting to the ESP8266 WiFi Theory AT Command Programming Commands Installing the latest AT command processor Assembling circuits USB to UART converters Breadboards Power Multi-meter / Logic probe / Logic Analyzer Sundry components Physical construction Recommended setup for programming ESP8266 Configuration for flashing the device Programming Boot mode ESP8266 – Software Development Kit (SDK) Include directories Compiling Loading a program into the ESP8266 Programming environments Compilation tools ar esptool.py esptool-ck gcc gen_appbin.py make nodemcu-flasher nm objcopy objdump xxd ESP8266 Linking Flashing over the air – FOTA Debugging ESP-IDF logging Logging to UART1 Run a Blinky Dumping IP Addresses Exception handling Debugging and testing TCP and UDP connections Android – Socket Protocol Android – UDP Sender/Receiver Windows – Hercules Curl Eclipse – TCP/MON httpbin.org ESP8266 Architecture Custom programs WiFi at startup Working with WiFi – ESP8266 Scanning for access points Defining the operating mode Handling WiFi events Station configuration Connecting to an access point Control and data flows when connecting as a station Being an access point The DHCP server Current IP Address, netmask and gateway WiFi Protected Setup – WPS Working with TCP/IP The espconn architecture TCP Sending and receiving TCP data Flow control TCP Error handling UDP Broadcast with UDP Ping request Name Service Multicast Domain Name Systems Installing Bonjour Working with SNTP ESP-NOW GPIOs Pullup and pull down settings GPIO Interrupt handling Expanding the number of available GPIOs ESP_PCF8574 C library PCF8574 JavaScript Library Working with I2C Working with SPI – Serial Peripheral Interface Hardware SPI The MetalPhreak/ESP8266_SPI_Driver Working with serial ESP8266 Task handling Timers and time Working with memory Working with flash memory Pulse Width Modulation – PWM Analog to digital conversion Sleep modes Watchdog timer Yielding control Security Mapping from Arduino Spiffs File System Partner TCP/IP APIs TCP/IP Sockets Handling errors Sockets – accept() Sockets – bind() Sockets – close() Sockets – closesocket() Sockets – connect() Sockets – fcntl() Sockets – freeaddrinfo() Sockets – getaddrinfo() Sockets – gethostbyname() Sockets – getpeername() Sockets – getsockname() Sockets – getsockopt() Sockets – htonl() Sockets – htons() Sockets – inet_ntop() Sockets – inet_pton() Sockets – ioctlsocket() Sockets – listen() Sockets – read() Sockets – recv() Sockets – recvfrom() Sockets – select() Sockets – send() Sockets – sendto() Sockets – setsockopt() Sockets – shutdown() Sockets – socket() Sockets – write() Socket data structures Sockets – struct sockaddr Sockets – struct sockaddr_in Java Sockets WebSockets A WebSocket browser app FreeRTOS WebSocket Mongoose WebSocket Web Servers Mongoose Programming using Eclipse Installing the Eclipse Serial terminal Web development using Eclipse Programming using the Arduino IDE Implications of Arduino IDE support Installing the Arduino IDE with ESP8266 support Tips for working in the Arduino environment Initialize global classes in setup() Invoking Espressif SDK API from a sketch Exception handling The SPIFFS file system The mkspiffs command The architecture of the Arduino IDE support Building ESP Arduino apps using the Eclipse IDE Reasons to consider using Eclipse over Arduino IDE Notes on using the Eclipse Arduino package Arduino ESP Libraries The WiFi library WiFi.begin WiFi.beingSmartConfig WiFi.beginWPSConfig WiFi.BSSID WiFi.BSSIDstr WiFi channel WiFi.config WiFi.disconnect WiFi.encryptionType WiFi.gatewayIP WiFi.getNetworkInfo WiFi.hostByName WiFi.hostname WiFi.isHidden WiFi.localIP WiFi.macAddress WiFi.mode WiFi.printDiag WiFi.RSSI WiFi.scanComplete WiFi.scanDelete WiFi.scanNetworks WiFi.smartConfigDone WiFi.softAP WiFi.softAPConfig WiFi.softAPdisconnect WiFi.softAPmacAddress WiFi.softAPIP WiFi.SSID WiFi.status WiFi.stopSmartConfig WiFi.subnetMask WiFi.waitForConnectResult WiFiClient WiFiClient WiFiClient.available WiFiClient.connect WiFiClient.connected WiFiClient.flush WiFiClient.getNoDelay WiFiClient.peek WiFiClient.read WiFiClient.remoteIP WiFiClient.remotePort WiFiClient.setLocalPortStart WiFiClient.setNoDelay WiFiClient.status WiFiClient.stop WiFiClient.stopAll WiFiClient.write WiFiServer WiFiServer WiFiServer.available WiFiServer.begin WiFiServer.getNoDelay WiFiServer.hasClient WiFiServer.setNoDelay WiFiServer.status WiFiServer.write IPAddress ESP8266WebServer ESP8266WebServer ESP8266WebServer.arg ESP8266WebServer.argName ESP8266WebServer.args ESP8266WebServer.begin ESP8266WebServer.client ESP8266WebServer.handleClient ESP8266WebServer.hasArg ESP8266WebServer.method ESP8266WebServer.on ESP8266WebServer.onFileUpload ESP8266WebServer.onNotFound ESP8266WebServer.send ESP8266WebServer.sendContent ESP8266WebServer.sendHeader ESP8266WebServer.setContentLength ESP8266WebServer.streamFile ESP8266WebServer.upload ESP8266WebServer.uri ESP8266mDNS library MDNS.addService MDNS.begin MDNS.update I2C – Wire Wire.available Wire.begin Wire.beginTransmission Wire.endTransmission Wire.flush Wire.onReceive Wire.onReceiveService Wire.onRequest Wire.onRequestService Wire.peek Wire.pins Wire.read Wire.requestFrom Wire.setClock Wire.write Ticker library Ticker attach attach_ms detach once once_ms EEPROM library EEPROM.begin EEPROM.commit EEPROM.end EEPROM.get EEPROM.getDataPtr EEPROM.put EEPROM.read EEPROM.write SPIFFS SPIFFS.begin SPIFFS.open SPIFFS.openDir SPIFFS.remove SPIFFS.rename File.available File.close File.flush File.name File.peek File.position File.read File.seek File.size File.write Dir.fileName Dir.next Dir.open Dir.openDir Dir.remove Dir.rename ESP library ESP.deepSleep ESP.eraseConfig ESP.getBootMode ESP.getBootVersion ESP.getChipId ESP.getCpuFreqMHz ESP.getCycleCount ESP.getFlashChipId ESP.getFlashChipMode ESP.getFlashChipRealSize ESP.getFlashChipSize ESP.getFlashChipSizeByChipId ESP.getFlashChipSpeed ESP.getFreeHeap ESP.getFreeSketchSpace ESP.getResetInfo ESP.getResetInfoPtr ESP.getSdkVersion ESP.getSketchSize ESP.getVcc ESP.reset ESP.restart ESP.updateSketch ESP.wdtDisable ESP.wdtEnable ESP.wdtFeed String library Constructor String.c_str String.reserve String.length String.concat String.equalsIgnoreCase String.startsWith String.endsWith String.charAt String.setCharAt String.getBytes String toCharArray String.indexOf String.lastIndexOf String.substring String.replace String.remove String.toLowerCase String.toUpperCase String.trim String.toInt String.toFloat Programming with JavaScript Smart.js Smart.js GPIO Setting up an HTTP server Debugging Espruino Editing and deploying code Working with variables Booting Espruino WiFi access Writing network socket applications using Espruino Writing a REST client using Espruino Writing a Web Server using Espruino Working with GPIO Working with I2C and JavaScript Debugging JavaScript Editing JavaScript Espruino ESP8266 Libraries Core JavaScript capabilities Running code at intervals Working with GPIO SPI Key differences from JavaScript Building Espruino Programming with Lua ESPlorer IDE GPIO with Lua WiFi with Lua Networking with Lua Programming with Basic Integration with Web Apps REST Services REST protocol ESP8266 as a REST client Making a REST request using Mongoose ESP8266 as a REST service provider Tasker AutoRemote DuckDNS Mobile apps Blynk Sample Snippets Forming a TCP connection Sample applications Sample – Light an LED based on the arrival of a UDP datagram Sample – Ultrasonic distance measurement Sample – WiFi Scanner Sample – Working with micro SD cards Sample – Playing audio from an event Sample – A changeable mood light Sample – Bootstrapping networking Sample Libraries Function list authModeToString checkError delayMilliseconds dumpBSSINFO dumpEspConn dumpRestart dumpState errorToString eventLogger eventReasonToString flashSizeAndMapToString setAsGpio setupBlink toHex Using FreeRTOS The architecture of a task in FreeRTOS Blocking and synchronization within RTOS Lists within RTOS ESP8266 – Building apps for RTOS Consoles with RTOS Debugging tips Developing solutions on Linux Building a Linux environment API Reference FreeRTOS API reference eTaskGetState pcTaskGetName xEventGroupClear xEventGroupCreate xEventGroupSetBits xEventGroupWaitBits xTaskCreate vTaskDelay vTaskDelayUntil vTaskDelete xTaskGetCurrentTaskHandle xTaskGetTickCount vEventGroupDelete vTaskList vTaskPrioritySet vTaskResume xTaskResumeAll vTaskResumeFromISR vTaskSuspend vTaskSuspendAll xQueueCreate vQueueDelete xQueuePeek xQueueReceive xQueueSend xQueueSendToBack xQueueSendToFront vSemaphoreCreateBinary xSemaphoreCreateCounting vSemaphoreGive xSemaphoreGiveFromISR vSemaphoreTake pvPortMalloc pvPortFree List Processing vListInitialise vListInitialiseItem vListInsert vListInsertEnd lwip Reference Sockets Timer functions os_delay_us 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 Functions system_adc_read system_deep_sleep_set_option system_get_boot_mode system_get_boot_version system_get_chip_id system_get_cpu_freq system_get_flash_size_map system_get_rst_info system_get_userbin_addr system_get_vdd33 system_init_done_cb system_os_post system_os_task system_phys_set_rfoption system_phys_set_max_tpw system_phys_set_tpw_via_vdd33 system_print_meminfo system_restart_enhance system_rtc_clock_cali_proc system_set_os_print system_show_malloc system_rtc_clock_cali_proc system_uart_swap system_soft_wdt_feed system_soft_wdt_stop system_soft_wdt_restart system_uart_de_swap system_update_cpu_freq os_memset os_memcmp os_memcpy os_malloc os_calloc os_realloc os_zalloc os_free os_bzero os_delay_us os_printf os_install_putc1 os_random os_get_random os_strlen os_strcat os_strchr os_strcmp os_strcpy os_strncmp os_strncpy os_sprintf os_strstr SPI Flash spi_flash_get_id spi_flash_erase_sector spi_flash_read spi_flash_set_read_func system_param_save_with_protect spi_flash_write system_param_load WiFi – ESP8266 wifi_fpm_close wifi_fpm_do_sleep wifi_fpm_do_wakeup wifi_fpm_get_sleep_type wifi_fpm_open wifi_fpm_set_sleep_type wifi_fpm_set_wakeup_cb wifi_get_channel wifi_get_ip_info wifi_get_macaddr wifi_get_opmode wifi_get_opmode_default wifi_get_phy_mode wifi_get_sleep_type wifi_get_user_fixed_rate wifi_get_user_limit_rate_mask wifi_set_broadcast_if wifi_get_broadcast_if wifi_set_sleep_type wifi_promiscuous_enable wifi_promiscuous_set_mac wifi_register_rfid_locp_recv_cb wifi_register_send_pkt_freedom_cb wifi_register_user_ie_manufacturer_recv_cb wifi_rfid_locp_recv_close wifi_rfid_locp_recv_open wifi_send_pkt_freedom wifi_set_channel wifi_set_event_handle_cb wifi_set_ip_info wifi_set_macaddr wifi_set_opmode wifi_set_opmode_current wifi_set_phy_mode wifi_set_promiscuous_rx_cb wifi_set_sleep_type wifi_set_user_fixed_rate wifi_set_user_ie wifi_set_user_limit_rate_mask wifi_set_user_rate_limit wifi_set_user_sup_rate wifi_status_led_install wifi_status_led_uninstall wifi_unregister_rfid_locp_recv_cb wifi_unregister_send_pkt_freedom_cb wifi_unregister_user_ie_manufacturer_recv_cb WiFi Station wifi_station_ap_change wifi_station_ap_number_set wifi_station_connect wifi_station_dhcpc_start wifi_station_dhcpc_status wifi_station_dhcpc_stop wifi_station_disconnect wifi_station_get_ap_info wifi_station_get_auto_connect wifi_station_get_config wifi_station_get_config_default wifi_station_get_connect_status wifi_station_get_current_ap_id wifi_station_get_hostname wifi_station_get_reconnect_policy wifi_station_get_rssi wifi_station_scan wifi_station_set_auto_connect wifi_station_set_cert_key wifi_station_clear_cert_key wifi_station_set_config wifi_station_set_config_current wifi_station_set_reconnect_policy wifi_station_set_hostname WiFi SoftAP wifi_softap_dhcps_start wifi_softap_dhcps_status wifi_softap_dhcps_stop wifi_softap_free_station_info wifi_softap_get_config wifi_softap_get_config_default wifi_softap_get_dhcps_lease wifi_softap_get_dhcps_lease_time wifi_softap_get_station_info wifi_softap_get_station_num wifi_softap_reset_dhcps_lease_time wifi_softap_set_config wifi_softap_set_config_current wifi_softap_set_dhcps_lease wifi_softap_set_dhcps_lease_time wifi_softap_dhcps_offer_option WiFi WPS wifi_wps_enable wifi_wps_disable wifi_wps_start wifi_set_wps_cb Upgrade APIs system_upgrade_flag_check system_upgrade_flag_set system_upgrade_reboot system_upgrade_start system_upgrade_userbin_check wifi_promiscuous_enable wifi_promiscuous_set_mac wifi_promiscuous_rx_cb wifi_get_channel wifi_set_channel Smart config APIs smartconfig_start smartconfig_stop SNTP API 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 Generic TCP/UDP APIs espconn_delete espconn_dns_setserver espconn_gethostbyname espconn_port espconn_regist_sentcb espconn_regist_recvcb espconn_send espconn_sendto ipaddr_addr IP4_ADDR IP2STR TCP APIs espconn_abort espconn_accept espconn_get_connection_info espconn_connect espconn_disconnect espconn_regist_connectcb espconn_regist_disconcb espconn_regist_reconcb espconn_regist_write_finish espconn_set_opt espconn_clear_opt espconn_regist_time espconn_set_keepalive espconn_get_keepalive espconn_secure_accept espconn_secure_ca_disable espconn_secure_ca_enable espconn_secure_set_size espconn_secure_get_size espconn_secure_delete espconn_secure_connect espconn_secure_send espconn_secure_disconnect 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 UDP APIs espconn_create espconn_igmp_join espconn_igmp_leave ping APIs ping_start ping_regist_recv ping_regist_sent mDNS APIs 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 GPIO – ESP32 gpio_config gpio_get_level gpio_input_get gpio_input_get_high gpio_intr_enable gpio_intr_disable gpio_isr_register gpio_output_set gpio_output_set_high gpio_set_direction gpio_set_intr_type gpio_set_level gpio_set_pull_mode GPIO – ESP8266 PIN_PULLUP_DIS PIN_PULLUP_EN PIN_FUNC_SELECT GPIO_ID_PIN GPIO_OUTPUT_SET GPIO_DIS_OUTPUT GPIO_INPUT_GET gpio_output_set gpio_input_get gpio_intr_handler_register gpio_pin_intr_state_set gpio_intr_pending gpio_intr_ack gpio_pin_wakeup_enable gpio_pin_wakeup_disable UART APIs UART_CheckOutputFinished UART_ClearIntrStatus UART_ResetFifo UART_SetBaudrate UART_SetFlowCtrl UART_SetIntrEna UART_SetLineInverse UART_SetParity UART_SetPrintPort UART_SetStopBits UART_SetWordLength UART_WaitTxFifoEmpty uart_init uart0_tx_buffer uart0_sendStr uart0_rx_intr_handler I2C Master APIs i2c_master_checkAck i2c_master_getAck i2c_master_gpio_init i2c_master_init i2c_master_readByte i2c_master_send_ack i2c_master_send_nack i2c_master_setAck i2c_master_start i2c_master_stop i2c_master_writeByte SPI APIs cache_flush spi_lcd_9bit_write spi_mast_byte_write spi_byte_write_espslave spi_slave_init spi_slave_isr_handler hspi_master_readwrite_repeat spi_test_init PWM APIs pwm_init pwm_start pwm_set_duty pwm_get_duty pwm_set_period pwm_get_period get_pwm_version set_pwm_debug_en(uint8 print_en) Bit twiddling ESP Now esp_now_add_peer esp_now_deinit esp_now_del_peer esp_now_get_peer_key esp_now_get_peer_role esp_now_get_self_role esp_now_init esp_now_register_recv_cb esp_now_register_send_cb esp_now_send esp_now_set_kok esp_now_set_peer_role esp_now_set_peer_key esp_now_set_self_role esp_now_unregister_recv_cb esp_now_unregister_send_cb SPIFFS esp_spiffs_deinit esp_spiffs_init SPIFFS_check SPIFFS_clearerr SPIFFS_close SPIFFS_closedir SPIFFS_creat SPIFFS_erase_deleted_block SPIFFS_errno SPIFFS_fflush SPIFFS_format SPIFFS_fremove SPIFFS_fstat SPIFFS_gc SPIFFS_gc_quick SPIFFS_info SPIFFS_lseek SPIFFS_mount SPIFFS_mounted SPIFFS_open SPIFFS_open_by_dirent SPIFFS_opendir SPIFFS_read SPIFFS_readdir SPIFFS_remove SPIFFS_rename SPIFFS_stat SPIFFS_unmount SPIFFS_write Lib-C atoi atol bzero calloc free malloc memcmp memcpy memmove memset os_get_random os_random printf puts rand realloc snprintf sprintf strcat strchr strcmp strcpy strcspn strdup strlen strncat strncmp strncpy strrchr strspn strstr strtok strtok_r strtol zalloc Data structures esp_spiffs_config station_config struct softap_config struct station_info struct dhcps_lease struct bss_info struct ip_info struct rst_info struct espconn esp_tcp esp_udp struct ip_addr ipaddr_t struct ping_option struct ping_resp struct mdns_info enum phy_mode GPIO_INT_TYPE System_Event_t espconn error codes STATUS Reference materials C++ Programming Simple class definition Lambda functions Ignoring warnings Eclipse ESPFS breakdown EspFsInit espFsOpen espFsClose espFsFlags espFsRead mkespfimage ESPHTTPD breakdown httpdInit httpdGetMimetype httpdUrlDecode httpdStartResponse httpdSend httpdRedirect httpdHeader httpdGetHeader httpdFindArg httpdEndHeaders Makefiles Forums Reference documents Github Github quick cheats SDK Single board computer comparisons Heroes Max Filippov – jcmvbkbc – GCC compiler for Xtensa Ivan Grokhotkov – igrr – Arduino IDE for ESP8266 development jantje – Arduino Eclipse Richard Sloan – ESP8266 Community owner Mikhail Grigorev – CHERTS – Eclipse for ESP8266 development Mmiscool – Basic Interpreter Areas to Research