ESP8266

There could be many common reasons for OTA failure. We recommend referring to the document ESP8266 FOTA Guide before you use the FOTA APIs.

Here are some quick checklist to troubleshoot OTA failure:

• Make sure that you select the correct Flash size when downloading the firmware to Flash.
• The first time you download a new firmware, always also download blank.bin.
• Confirm that user1.bin and user2.bin (optional) downloaded to the correct locations.
• Make sure you generate user1.bin and user2.bin with the same Flash/boot configuration options!

Users can serve updates via their own custom server. The server should be able to serve HTTP requests and should have device control features.

For API reference, please visit: http://iot.espressif.cn/#/api-en/.

Here are some probable reasons why SmartConfig might fail:

• APP version is not matched with SDK or SmartConfig version.
• The router under configuration is a 5 GHz-only router.
• Some other API was called during SmartConfig (please do not call any APIs under SmartConfig is done).
• When using AT command, do not stop SmartConfig before device gets IP from router.

If the above did not solve your problem, please send us the debug log so that we can analyze the problem.

Yes, it does. ESP8266 can run as a server in both SoftAP and Station modes.

• When running as a server in SoftAP mode, clients can directly access the ESP8266 host or server at 192.168.4.1 (default) IP address.
• When the server is accessed via a router, the IP address should be the one allocated to the ESP8266 by the router.
• When using SDK to write native code, please use espconn structure and related APIs.
• When using AT commands, start a server using AT+CIPSERVER command.

There is an example of how to define an AT command “AT+TEST” in AT demo folder of Non-OS SDK (\ESP8266_NONOS_SDK\examples\at\user\user_main.c). The structure at_funcationType is used to define the four variants of an AT command. We use command “AT+TEST” as an example and demonstrate how it can be implemented.

1. Type at_testCmd: Test command in the format of AT+TEST=?. In AT demo, the registered callback is at_testCmdTest. The test demand could be programmed to return the range of the parameter value. If at_testCmd is registered as NULL, it will not be implemented.
2. Type at_queryCmd: Query command in the format of AT+TEST=?. In AT demo, the registered callback is at_queryCmdTest. The test demand could be programmed to return the current value. If at_queryCmdTest is registered as NULL, it will not be implemented.
3. Type at_setupCmd: Setup command in the format of AT+TEST=parameter1,parameter2,……,. In AT demo, the registered callback is at_setupCmdTest. The setup command can be programmed to set the parameter value. If at_setupCmdTest is registered as NULL, it will not be implemented.
4. Type at_exeCmd: Execution command in the format of AT+TEST. In AT demo, the registered callback is at_exeCmdTest. The execution command can be programmed to execute an operation. If at_exeCmdTest is registered as NULL, it will not be implemented.

Users can add customized AT command based on ESP8266’s own AT commands, by using ESP8266_NONOS_SDK\examples\at sample code. The maximum string length of AT command supported by SDK is 128 bytes (including terminator “\r\n”). The length of AT command and parameters are not individually limited.

For example,

AT+CMDTEST=param1,param2,param3,….paramN\r\n

strlen(“AT+CMDTEST=param1,param2,param3,....paramN\r\n”)<=128 Bytes

For details of SDK please refer to ESP8266 SDKs & Demos.

When connected to routers, ESP8266 will enter modem_sleep in STA mode only, which will cause the changes of the internal chip currents and reference values, and thus result in abnormal ADC sampling.

If a high accuracy is required, please use system_adc_fast_read API. But RF circuitry should be shut down before measuring and Wi-Fi will be disconnected. For an relatively lower accuracy when readings’ difference of 1 or 2 can be tolerated, Wi-Fi can be configured to non_sleep mode.

For lower accuracy, the user may enter sleep mode. Power consumption is lower in this case.

tx_addr is the sending address;

tx_cmd is the sending command;

tx_rep is the repeating time.

1. For configuring data format of UART communication, please refer to file uart.c in SDK/driver_lib/driver/.
2. The two steps to configure hardware flow control in UART communication are as follows:

(1) Set the following attribute to 1 in uart.h:

#define UART_HW_RTS 1 //set 1: enable uart hw flow control RTS, PIN MTDO, FOR UART0

#define UART_HW_CTS 1 //set1: enable uart hw flow contrl CTS , PIN MTCK, FOR UART0

(2) Configure hardware flow control threshold.

The threshold of hardware flow control is highlighted by the red square in the following screenshot. When the number of bytes in RXFIFO is larger than 110, RTS will be pulled to logic high.

Please note that the SDIO hardware only supports the device or slave profile, i.e. it cannot act as a host to control SDIO devices such as SD cards.

Whether the problems happens or not depends on the design of the LED driver. If the LED is powered on low level and IO is pulled to a logic low upon power-on, then the LED may blink. The reason is that except GPIO4 and GPIO5 related to Flash, pull-ups for all IO pins are enabled.

Solution:

1. Disable pull-ups in user_init upon power-on.
2. If the first method doesn’t work, please contact us to obtain a customized boot.bin file. IO pull-ups will be disabled when boot.bin is loaded into RAM, which is earlier than when user.bin is called.

If you use the soft change APIs found in the SDK demo, such as light_set_aim and light_set_aim_r, these APIs are optimized for lighting applications and therefore cause smooth transitions.

For changing the PWM quickly for other applications, please use pwm_set_duty to set the duty cycle desired and call pwm_start to implement new duty cycle immediately.

Please find the GPIO pin list and register description here:

ESP8266 Technical Reference.

The data buffer on the HSPI peripheral is 16 words (or 64 bytes). It is word accessible and is a continuous block on the memory map. The buffer is very flexible in the manner that the data contained can be transmitted LSB or MSB first and also in little-endian or big-endian fashion, which eliminates the need for software manipulation of data block sequence. With the HSPI buffer employed, the channel utilization can exceed 90% at moderate clock speeds.

Use

CLEAR_PERI_REG_MASK(SPI_USER(spiNum), SPI_USR_MISO_HIGHPART );

to enable the upper part of the data buffer to be used for data transfer.

wifi_station_set_auto_connect

wifi_station_ap_number_set

wifi_set_phy_mode

wifi_softap_set_config

wifi_station_set_config

wifi_set_opmode

system_restart_enhance

system_restore

system_upgrade_reboot

No, all read/write operations must be aligned to the 4-byte (word) boundary. We highly recommend performing operations on blocks, instead of frequent, small data operations.

Here is an example of flash texting routine:

uint32 sector is start sector, and uint32 cnt is sector count to erase.

#define FLASH_WRITE_LEN_BYTE (1024*4)

#define FLASH_WRITE_CONTENT (0X10)

void flash_sector_rw_test(uint32 sector,uint32 cnt)

{

      char* w_data=(char*)os_malloc(FLASH_WRITE_LEN_BYTE);

      uint32 flash_operate=0;

      uint32 i=0;

      uint8 status=0;

      os_printf("Test Sector is 0x%x\n",sector);

      if(NULL==w_data){

         os_printf("Memory little\n");

         return;

}

os_memset(w_data,FLASH_WRITE_CONTENT,FLASH_WRITE_LEN_BYTE);

for(i=0;i<cnt;i++){

      if(spi_flash_erase_sector(sector+i)==0)

       {

         os_printf("erase sector0x%x ok\n",sector+i);

      }

      else{

         os_printf("Err:erase sector0x%x err\n",sector+i);

      }

}

for(i=0;i<cnt;i++){

      if(spi_flash_write((sector+i)*(FLASH_WRITE_LEN_BYTE),

(uint32*)w_data,FLASH_WRITE_LEN_BYTE)==0)

      {

         os_printf("write sector 0x%x ok\n",sector+i);

      }

      else{

         os_printf("Err:write sector 0x%x err\n",sector+i);

      }

}

for(i=0;i<cnt;i++){

         os_memset(w_data,0x00,FLASH_WRITE_LEN_BYTE);

      if(spi_flash_read((sector+i)*(FLASH_WRITE_LEN_BYTE), (uint32*)w_data,FLASH_WRITE_LEN_BYTE)==0)

      {

         uint32 j=0;

         for(j=0;j<FLASH_WRITE_LEN_BYTE;j++){

         if(*(w_data+j)!=FLASH_WRITE_CONTENT){

            os_printf("Err Flash read w_data[%d]=0x%x\n",j,w_data[j]);

            //status=1;

         }

         if(*(w_data+j)==FLASH_WRITE_CONTENT&&j==FLASH_WRITE_LEN_BYTE-1)

         {

            os_printf("Sector0x%x Test Ok\n",sector+i);

               }

}

      }

This is because hardware flow control is no enabled. The transparent transmission mode uses TCP protocol, with 1460 bytes (which depends on the protocol stack) of data in every packet. As long as the network is good and the buffer is not consumed, data can be transmitted continuously. In transparent transmission mode, when the interval of time for serials to receive data is over 20 ms, the transmission is assumed to have ended and the received data will be transmitted to the network. So data may be lost if the network connectivity is not good. Please enable flow control to prevent data loss.

Except XPD_DCDC, other GPIOs can be configured to high level.

The GPIO default level status after booting is: except 6 SDIO +GPIO4+GPIO5+GPIO16, all the other GPIOs have internal pull-up resistors. To pull down the GPIOs, external pull-down or inverting circuit is required.

Note: The external voltage level for GPIO cannot be 5V. GPIO4/5 cannot be pulled up with external 1M resistor. Please use 100K resistor instead.

The ESP8266 is highly integrated with RF circuits and digital control circuits. When booting, functions such as RF calibration may draw an appreciable amount of power. The maximum analog power (instantaneous) may be considered to be 500mA and the digital circuits may draw a peak current of around 200 mA. The normal operational current is typically around 100 mA, depending on the application and circuit design. Therefore, your design must provide for a voltage regulator that can provide 500 mA without suffering a drop in the output voltage which is outside the operating specifications.

The SPI flash memory is an integral part of the system as it stores the user program and data. To ensure compatibility of digital logic, SPI flash voltage should match with the GPIO logic voltage level.

The current SDK allows disabling the software watchdog only. The following methods can be taken to avoid watchdog reset when user program occupies CPU for too long:

1. If your routine needs a time frame of duration between software reset and hardware watchdog reset, you may use system_soft_wdt_stop () to disable the software watchdog. After the program has been executed, you can restart the software watchdog with system_soft_wdt_restart ().
2. You may feed the watchdog in between your code by adding system_soft_wdt_feed () such that the watchdog is updated before it issues a reset.

For Non-OS SDK users, memory leak debugging can be achieved by defining MEMLEAK_DEBUG to enable the debugging function.

Calls to os_malloc, os_zalloc, os_calloc, os_realloc, os_free is recorded and then the API system_print_meminfo() can be used to print heap memory usage.

Steps to debug memory leaks: 

1. Modify the main makefile in the project and define DMEMLEAK_DEBUG after CONFIGURATION_DEFINES. 

i.e. CONFIGURATION_DEFINES = -DMEMLEAK_DEBUG

2. In user code, such as the user_main.c file, please include the header file “mem.h” and the function:

#include “mem.h"

bool ICACHE_FLASH_ATTR check_memleak_debug_enable ()

{

          return MEMLEAK_DEBUG_ENABLE;

}

3. Call system_print_meminfo() API where the cause of memory leakage might possibly be. We recommend using this API at key positions only.

Fatal exceptions can be traced down if you have the assembly file (*.S) that was used to generate the binary. For example, should you encounter an exception when running user1.bin:

Fatal exception (28)：
epc1=0x4025bfa6, epc2=0x00000000, epc3=0x00000000,
excvaddr=0x0000000f, depc=0x00000000

In this case, you should inspect 0x4025bfa6 in user1.S to find out the cause of the exception.

When running flash.bin and irom0text.bin, the cause of the exception can be found in eagle.S.

Please refer to ESP8266 Non-OS SDK API Reference and ESP8266 RTOS SDK API Reference (link: espressif.com/en/support/download/documents) for the SDK you are using for details. However, as a general rule, functions declared as ICACHE_FLASH_ATTR must not be called from within a hardware interrupt handler when Non-OS SDK is used. Also, do not occupy the CPU for long when inside an interrupt handler.

For ESP8266_Non-OS SDK:

Functions attributed with ICACHE_FLASH_ATTR are located in the IROM section. They will run from cache when called by CPU. Conversely, functions without ICACHE_FLASH_ATTR are loaded into IRAM upon power- on. Due to limited IRAM, we can not load all the codes into IRAM at one time. So most functions are attributed with ICACHE_FLASH_ATTR and loaded into IROM.

Note: Do not use ICACHE_FLASH_ATTR-functions within an interrupt handler, as it may conflict with the Flash R/W operations.

For ESP8266_RTOS SDK:

Functions are located in the IROM section by default and do not need to be attributed with ICACHE_FLASH_ATTR. Interrupt handlers can also run from IROM. Hence, if functions called frequently need to be run from IRAM, they should be attributed with IRAM_ATTR.

This means that the code is too large for IROM. Here are some suggestions to resolve the problem:

For SDK_v0.9.5 or later versions:

1. Compile with default configuration to generate eagle.flash.bin and eagle.irom0text.bin.

(1) If the total size of eagle.flash.bin and eagle.irom0text.bin is more than 236 KB, you will need a new Flash chip larger than 512 KB.

(2) If the total size of eagle.flash.bin and eagle.irom0text.bin is less than 236 KB, continue with step 2.

2. Revise the file eagle.app.v6.new.512.app1.ld in SDK/ld as follows:

In the line

rom0_0_seg: org = 0x40201010, len = 0x2B000,

change the value of len according to the size of your eagle.irom0text.bin.

For example, if the size of eagle.irom0text.bin is 179 KB, change the configuration to

irom0_0_seg: org = 0x40201010, len = 0x2D000

3. Now, compile and generate user1.bin by selecting boot_v.1.2+.

PS.

In your source code, load into IRAM functions without “ICACHE_FLASH_ATTR” which can be 32 KB at most; load into IROM functions with "ICACHE_FLASH_ATTR" in irom0_0_seg.

Due to limited RAM, functions in IRAM will be loaded to ram and run upon power-on; functions in IROM will be loaded to cache from Flash and run only if it is called.

Read and write accesses to the RAM must be aligned to the 4-byte (word) boundary, so is pointer conversion. Otherwise, the conversion failure will cause malfunction. For example, please use os_memcpy (memcpy) to convert the pointer instead of float temp = *((float*)data).

1. wifi_set_ip_info and wifi_set_macaddr are only valid when called from user_init.
2. It is recommended to call system_timer_reinit from user_init, otherwise, all timers need to be armed.
3. If wifi_station_set_config is called from user_init, the lower layer will automatically connect to the corresponding router without calling wifi_station_connect.
4. wifi_station_set_auto_connect is used to configure the device whether to automatically connect to the saved router upon start up. For example, if the interface is called from user_init with automatic router connection disabled, the device will not automatically connect to the router that time. If the interface is called elsewhere, then the device will not automatically connect to the router next time.

1. Model:

(1) FRC1’s reference clock is 80M. The division factor can be configured to 1, 16 and 256. Difference of division factor will affect the duration of each tick.

(2) FRC1 is a countdown timer. Interrupts will be triggered when the value of COUNT_VALUE decreases to 0. The value of COUNT_VALUE decreases by 1 at every tick.

(3) FRC1 can be configured as auto-feed-mode or non-auto-feed-mode.

Auto-feed-mode: When interrupts are triggered, COUNT_VALUE will automatically take the value of FRC1_LOAD_VALUE and begin the decrement operation.

Non-auto-feed-mode: When interrupts are triggered, COUNT_VALUE will be set to the maximum value, 0x7fffff, and counting begins.

(4) FRC interrupts can be configured as FRC1 interrupt source and NMI interrupt source.

NMI interrupt is an interrupt that can not be masked by CPU. NMI interrupt is LEVEL3 interrupt in ESP8266 while other interrupts are LEVEL1 interrupts. NMI interrupt prevails over any other interrupts lower in priority.

2. Note on SDK HW_TIMER

The division factor of SDK hw-timer is 16, the duration of each tick is 0.2 μs. The parameter of hw_timer_arm can be configured to μs, with a maximum value of 1677000 μs.

After ESP8266 connects to an AP, it will save the AP’s channel information in RTC memory.

• • When you reset ESP8266 by software or the ESP8266 wakes up from Deep-sleep mode, it will read the AP’s channel information from RTC memory, then try to connect the AP in the channel.
  • But if the ESP8266 goes through a power cycle or is hardware reset, the RTC memory will be cleared. The ESP8266 will then scan through all the channels, which takes some time.

You can try the following solution to save and restore the AP’s channel information when you power on or reset ESP8266 by hardware. By doing so, you can avoid the situation where ESP8266 scans all the channels to search the AP it connected to last time. This can help speed up connection time on startup.

1. 1. After ESP8266 connects with an AP, use function wifi_get_channel to read current AP’s channel information, then you can save the AP’s channel information in the SPI Flash. Before writing the channel information, you should verify that the channel information is valid.
   2. When the ESP8266 is then reset by hardware or goes through a power cycle, user firmware can read the saved channel information from flash. By calling WRITE_PERI_REG(0x600011f4, 1 << 16 | channel), the AP’s channel information can be written to the RTC memory. The channel information can be directly accessed from the RTC memory to help speed up connection time.
   3. Note that the auto connection function should be enabled for the ESP8266 to read the AP’s channel information, and to connect to the AP in that channel.

Only channel information is cached in RTC memory. The other information (such as SSID and Password) is saved in Flash, when you call the function wifi_station_set_config.

Note: If your application requires very frequent hardware resets or goes through frequent power cycles, it is recommended that you use external RTC memory for backing up channel information. Very frequent writes to the flash memory is not recommended as the flash-write cycles are limited.

ESP8266 does support SoftAP + Station co-existing mode, however, ESP8266 has only one hardware channel which is shared between the Station interface and the SoftAP interface. As a result, ESP8266 SoftAP will dynamically adjust the channel value to be consistent with ESP8266 Station, which may cause the following cases.

Case 1

1. ESP8266 Station is connected to a router (assume the channel number is 6);
2. ESP8266 SoftAP mode is activated using wifi_softap_set_config;
3. The API will return true if configuration is correct, but the channel number will adjust automatically to be the same as that of the ESP8266 Station interface (which is 6 in this case).

Case 2

1. wifi_softap_set_config is called and ESP8266 is configured to SoftAP mode (assume the channel number is 5);
2. Other stations are connected to ESP8266 SoftAP;
3. ESP8266 Station is connected to the router (assume the router channel number is 6);
4. ESP8266 SoftAP will automatically adjust the channel number to be the same as that of the ESP8266 Station (6 in this case);
5. As the channel changed, the station that is connected to the ESP8266 SoftAP will lose Wi-Fi connectivity.

Case 3

1. Other stations are connected to the ESP8266 SoftAP.
2. If ESP8266 Station keeps trying to scan for or connect to a router, ESP8266 SoftAP may lose connectivity, and UDP or ping packet loss may occur.

This is because ESP8266 Station will scan through channels to find the target router. Therefore, ESP8266 SoftAP keeps changing channel as well, leading to connectivity problems.

In such case, users can set the timer and call wifi_station_disconnect on expiry to stop ESP8266 Station from trying to connect to the router. The other way is to call wifi_station_set_reconnect_policy and wifi_station_set_auto_connect at the beginning of the configuration to prohibit ESP8266 Station from reconnecting to the router.

There are the following methods to connect ESP8266 device to wireless router:

1. Enable ESP8266 Smartconfig. ESP8266 device can scan attribute packets in sniffer mode and connect to the router.
2. Enable SoftAP mode for ESP8266 device to connect to smart phone and establish stable TCP/UDP connection. Then the smart phone can send SSID and password.
3. Enable WPS configuration, which requires adding buttons to ESP8266 device or using the mobile app to control WPS after connecting the device to SoftAP.