ESP32 Arduino General Tutorial - Chapter 3

Timer

Timers are very important components in SoCs. They can help the system perform tasks periodically, conduct timeout detection, measure event intervals, and so on.

timerBegin

hw_timer_t * timerBegin(uint32_t frequency);

Function: Set up and start a timer
Parameters:

• frequency: Timer frequency (in Hz)

Return value: Returns NULL on error, and the timer structure on success

timerEnd

void timerEnd(hw_timer_t * timer);

Function: Stop the timer
Parameters:

• timer: Timer structure

timerStart / timerStop / timerRestart

void timerStart(hw_timer_t * timer);  //Start the timer
void timerStop(hw_timer_t * timer);  //Stop the timer
void timerRestart(hw_timer_t * timer);  //Restart the timer (will reset the count)

Function: Start/stop/restart the timer
Parameters:

• timer: Timer structure

timerWrite

void timerWrite(hw_timer_t * timer, uint64_t val);

Function: Set the timer count value
Parameters:

• timer: Timer structure
• val: Count value

timerRead

uint64_t timerRead(hw_timer_t * timer);

Function: Read the timer count value
Parameters:

• timer: Timer structure

timerReadMicros / timerReadMilis / timerReadSeconds

uint64_t timerReadMicros(hw_timer_t * timer);  //Return the count value in microseconds
uint64_t timerReadMilis(hw_timer_t * timer);  //Return the count value in milliseconds
double timerReadSeconds(hw_timer_t * timer);  //Return the count value in seconds

Function: Read the timer count value
Parameters:

• timer: Timer structure

timerAttachInterrupt

void timerAttachInterrupt(hw_timer_t * timer, void (*userFunc)(void));

Function: Attach an interrupt to the timer
Parameters:

• timer: Timer structure
• userFunc: The function to be called when the interrupt is triggered

timerAlarm

void timerAlarm(hw_timer_t * timer, uint64_t alarm_value, bool autoreload, uint64_t reload_count);

Function: Configure timer triggering
Parameters:

• timer: Timer structure
• alarm_value: Alarm threshold
• autoreload: Enable/disable auto-reload
• reload_count: Number of auto-reloads (takes effect when auto-reload is enabled, 0 = unlimited)

Sleep

Sleep mode allows the ESP32 to enter a dormant state, significantly reducing device power consumption.

Introduction to Sleep Modes

Setting Wake-up Sources

The ESP32 supports multiple wake-up sources, including: IO wake-up, touch wake-up, and timer wake-up.

esp_sleep_enable_ext0_wakeup

Note

• The pin must be an RTC GPIO.

esp_err_t esp_sleep_enable_ext0_wakeup(gpio_num_t ext0_gpio_num, int level_threshold);

Function: Configures the EXT0 external wake-up source, which wakes up the ESP32 through a level change on a single GPIO pin.
Parameters:

• ext0_gpio_num: The pin used to wake up the ESP32.
• level_threshold: Wake-up mode
  • 1: Wake up on rising edge.
  • 0: Wake up on falling edge.

Return value: Returns ESP_OK on success, error code on failure.

esp_sleep_enable_ext1_wakeup_io

Note

• The pin must be an RTC GPIO.

esp_err_t esp_sleep_enable_ext1_wakeup_io(uint64_t mask, esp_ext1_wakeup_mode_t mode);

Function: Configures the EXT1 external wake-up source, supporting multiple GPIOs and setting them to "any valid" or "all valid" to wake up the ESP32.
Parameters:

• mask: Pin mask bits.
• mode: Wake-up mode
  • ESP_EXT1_WAKEUP_ALL_LOW: Wake up only when all selected pins are low.
  • ESP_EXT1_WAKEUP_ANY_HIGH: Wake up when any selected pin is high.

Return value: Returns ESP_OK on success, error code on failure.

touchSleepWakeUpEnable

void touchSleepWakeUpEnable(IO, uint8_t threshold);

Function: Enables Touch Sensor Wake-up, which detects capacitance changes on a touch pin during sleep to wake up the ESP32.
Parameters:

• mask: Pin mask bits.
• mode: Wake-up mode
  • ESP_EXT1_WAKEUP_ALL_LOW: Wake up only when all selected pins are low.
  • ESP_EXT1_WAKEUP_ANY_HIGH: Wake up when any selected pin is high.

Return value: Returns ESP_OK on success, error code on failure.

esp_sleep_enable_timer_wakeup

void esp_sleep_enable_timer_wakeup(time_in_us)

Function: Sets Timer Wake-up, which automatically wakes up the ESP32 after a specified time in sleep mode.
Parameters:

• time_in_us: Wake-up time in microseconds.

Return value: Returns ESP_OK on success, error code on failure.

Sleep Functions

esp_light_sleep_start

esp_light_sleep_start();

Function: Enters light sleep mode.
Parameters:

• mask: Wake-up time.

Return value: Returns ESP_OK on success, error code on failure.

esp_wifi_start_sleep / esp_wifi_stop_sleep

esp_wifi_start_sleep();
esp_wifi_stop_sleep();

Function: Controls WiFi sleep or wake-up.
Return value: Returns ESP_OK on success, error code on failure.

esp_deep_sleep_start

esp_deep_sleep_start();

Function: Enters deep sleep mode.
Return value: Returns ESP_OK on success, error code on failure.

Other Functions

esp_sleep_get_wakeup_cause

esp_sleep_get_wakeup_cause();

Function: Gets the wake-up cause.
Return value: Returns the wake-up source on success.

• ESP_SLEEP_WAKEUP_EXT0: Wake-up caused by external signal using RTC_IO.
• ESP_SLEEP_WAKEUP_EXT1: Wake-up caused by external signal using RTC_CNTL.
• ESP_SLEEP_WAKEUP_TIMER: Wake-up caused by timer.
• ESP_SLEEP_WAKEUP_TOUCHPAD: Wake-up caused by touchpad.
• ESP_SLEEP_WAKEUP_ULP: Wake-up caused by ULP program.

Preferences

Preferences can be regarded as a replacement for Arduino EEPROM. It uses a part of the ESP32's ROM to store data, which will not be lost even when the device is powered off.

begin

bool begin(const char * name, bool readOnly=false, const char* partition_label=NULL);

Function: Opens the storage space named "name" from the NVS partition.
Parameters:

• name: The name of the space, with a maximum length of 15 bytes.
• readOnly: Read-write mode (read-write mode by default)
  • false: Read-write mode
  • true: Read-only mode
• partition_label: The name of the NVS partition in which to open the namespace (opens in NVS by default)

Return value: Returns true if opened successfully.

clear

bool clear();

Function: Clears all values in the namespace.
Return value: Returns true on success.

remove

bool remove(const char * key);

Function: Deletes the key-value pair in the open space.
Parameters:

• key: The name of the key to be deleted.

Return value: Returns true on success.

freeEntries

size_t freeEntries();

Function: Gets the number of available key-value table entries.
Return value: Returns the number of entries if they exist; otherwise, returns 0.

isKey

bool isKey(const char * key);

Function: Checks if a key-value pair exists.
Parameters:

• key: The name of the key to be checked.

Return value: Returns true if it exists.

getType

PreferenceType getType(const char* key);

Function: Gets the key type.
Parameters:

• key: The name of the key to be obtained.

Return value: Returns the type as shown in the supported data table if it exists; returns 10 (PT_INVALID) on failure.

Writing Key-Values

size_t putBool(const char* key, bool value);  //Writes bool type
size_t putChar(const char* key, int8_t value);  //Writes char type
size_t putUChar(const char* key, uint8_t value);  //Writes uChar type
size_t putShort(const char* key, int16_t value);  //Writes short type
size_t putUShort(const char* key, uint16_t value);  //Writes uShort type
size_t putInt(const char* key, int32_t value);  //Writes int type
size_t putUInt(const char* key, uint32_t value);  //Writes uInt type
size_t putLong(const char* key, int32_t value);  //Writes long type
size_t putULong(const char* key, uint32_t value);  //Writes uLong type
size_t putLong64(const char* key, int64_t value);  //Writes Long64 type
size_t putULong64(const char* key, uint64_t value);  //Writes uLong64 type
size_t putFloat(const char* key, float_t value);  //Writes float type
size_t putDouble(const char* key, double_t value);  //Writes double type
size_t putString(const char* key, const char* value);  //Writes string type
size_t putString(const char* key, String value);  //Writes string type
size_t putBytes(const char* key, const void* value, size_t len);  //Writes variable-byte type

Function: Writes key-value pairs.
Parameters:

• key: The name of the key to be written; if it does not exist, the key will be created.
• value: The value of the corresponding type.
• len: The number of bytes (only for the putBytes function).

Return value: Returns the number of bytes written on success.

Reading Key-Values

bool getBool(const char* key, bool defaultValue = false);
int8_t getChar(const char* key, int8_t defaultValue = 0);
uint8_t getUChar(const char* key, uint8_t defaultValue = 0);
int16_t getShort(const char* key, int16_t defaultValue = 0)
uint16_t getUShort(const char* key, uint16_t defaultValue = 0)
int32_t getInt(const char* key, int32_t defaultValue = 0)
uint32_t getUInt(const char* key, uint32_t defaultValue = 0)
int32_t getLong(const char* key, int32_t defaultValue = 0)
uint32_t getULong(const char* key, uint32_t defaultValue = 0)
int64_t getLong64(const char* key, int64_t defaultValue = 0)
uint64_t getULong64(const char* key, uint64_t defaultValue = 0)
float_t getFloat(const char* key, float_t defaultValue = NAN)
double_t getDouble(const char* key, double_t defaultValue = NAN)
size_t getString(const char* key, char* value, size_t len);
String getString(const char* key, String defaultValue = String());
size_t getBytes(const char* key, void * buf, size_t len);
size_t getBytesLength(const char* key)

Function: Reads key-value pairs.
Parameters:

• key: The name of the key to be checked.
• defaultValue, value, buf: Data buffers.

Return value: Returns true if it exists.