System

Task Queue

Sming has a task queue which allows execution of a function to be deferred until the system is less busy. This is done by calling SystemClass::queueCallback().

Callbacks are executed as soon as possible, and allow other higher priority tasks (such as servicing the WiFi stack) to be handled in a timely manner.

A common use for the queue is to initiate processing from an interrupt service routine.

You must not spend too much time in the callback. How much time depends on the nature of your application, but tasks consuming more than 100ms will probably affect responsiveness and should be broken into smaller chunks. You might do this by wrapping such tasks in a class together with some state information. At the end of the initial callback if there is further work to be done simply make another call to queueCallback().

The task queue size is fixed, so the call to queueCallback() will fail if there is no room.

TASK_QUEUE_LENGTH: Maximum number of entries in the task queue (default 10).

ENABLE_TASK_COUNT

If problems are suspected with task queuing, it may be getting flooded. For this reason you should check the return value from queueCallback().

You can enable this option to keep track of the number of active tasks, SystemClass::getTaskCount(), and the maximum, SystemClass::getMaxTaskCount().

By default this is disabled and both methods will return 255. This is because interrupts must be disabled to ensure an accurate count, which may not be desirable.

API Documentation

group system

Access to the ESP8266 system Provides system control and monitoring of the ESP8266.

Typedefs

using TaskCallback32 = void (*)(uint32_t param): Task callback function type, uint32_t parameter.

Note

Callback code does not need to be in IRAM

using TaskCallback = void (*)(void *param): Task callback function type, void* parameter.

Note

Callback code does not need to be in IRAM

using TaskDelegate = Delegate<void()>: Task Delegate callback type.

using SystemReadyDelegate = TaskDelegate : Handler function for system ready.

Enums

enum CpuFrequency

Common CPU frequencies.

Values:

enumerator eCF_80MHz

enumerator eCF_125MHz

enumerator eCF_133MHz

enumerator eCF_160MHz

enumerator eCF_240MHz

enum DeepSleepOptions

Deep sleep options.

Values:

enumerator eDSO_RF_CAL_BY_INIT_DATA: RF_CAL or not after deep-sleep wake up, depends on init data byte 108.

enumerator eDSO_RF_CAL_ALWAYS: RF_CAL after deep-sleep wake up, there will be large current.

enumerator eDSO_RF_CAL_NEVER: no RF_CAL after deep-sleep wake up, there will only be small current.

enumerator eDSO_DISABLE_RF: disable RF after deep-sleep wake up, just like modem sleep, there will be the smallest current.

enum SystemState

System state.

Values:

enumerator eSS_None: System state unknown.

enumerator eSS_Intializing: System initialising.

enumerator eSS_Ready: System ready.

Variables

SystemClass System

Global instance of system object.

Note

Use system.function to access system functions

Note

Example:

system.reset();

class ISystemReadyHandler

#include <System.h>

Interface class implemented by classes to support on-ready callback.

Subclassed by WDTClass, WifiSniffer

Public Functions

virtual void onSystemReady() = 0: Handle system ready events.

class SystemClass

#include <System.h>

System class.

Public Functions

inline bool isReady()

Check if system ready.

Return values:: bool – True if system initialisation is complete and system is now ready

void restart(unsigned deferMillis = 0)

Request a restart of the system.

Note

A delay is often required to allow network callback code to complete correctly. The restart is always deferred, either using the task queue (if deferMillis == 0) or using a timer. This method always returns immediately.

Parameters:: deferMillis – defer restart request by a number of milliseconds

inline bool setCpuFrequency(CpuFrequency freq)

Set the CPU frequency.

Parameters:: freq – Frequency to set CPU
Return values:: bool – true on success

inline CpuFrequency getCpuFrequency()

Get the CPU frequency.

Return values:: CpuFrequency – The frequency of the CPU

bool deepSleep(uint32_t timeMilliseconds, DeepSleepOptions options = eDSO_RF_CAL_BY_INIT_DATA)

Enter deep sleep mode. Deep sleep turns off processor and keeps only the RTC memory active.

Note

Determine reset cause like this:

auto info = system_get_rst_info();
if(info->reason == REASON_DEEP_SLEEP_AWAKE) {
    // ...
}

Note

ESP8266: Ensure GPIO 16 (XPD_DCDC) is connected to RST (EXT_RSTB). and call pinMode(16, WAKEUP_PULLUP) to enable wakeup from deep sleep.

Parameters:

timeMilliseconds – Quantity of milliseconds to remain in deep sleep mode
options – Deep sleep options

inline void onReady(SystemReadyDelegate readyHandler)

Set handler for system ready event.

Note

if system is ready, callback is executed immediately without deferral

Parameters:: readyHandler – Function to handle event

inline void onReady(ISystemReadyHandler *readyHandler)

Set handler for system ready event.

Note

if system is ready, callback is executed immediately without deferral

Parameters:: readyHandler – Function to handle event

Public Static Functions

static bool initialize()

System initialisation.

Note

Called by user_main: applications should not call this function or the task queue will be re-initialised and any currently queued tasks won’t be called.

Return values:: bool – true on success

static inline bool queueCallback(TaskCallback32 callback, uint32_t param = 0)

Queue a deferred callback.

Note

It is important to check the return value to avoid memory leaks and other issues, for example if memory is allocated and relies on the callback to free it again. Note also that this method is typically called from interrupt context so must avoid things like heap allocation, etc.

Parameters:

callback – The function to be called
param – Parameter passed to the callback (optional)

Return values:

bool – false if callback could not be queued

static bool queueCallback(TaskCallback callback, void *param = nullptr): Queue a deferred callback, with optional void* parameter.

static bool queueCallback(InterruptCallback callback): Queue a deferred callback with no callback parameter.

static bool queueCallback(TaskDelegate callback)

Queue a deferred Delegate callback.

Note

Provides flexibility and ease of use for using capturing lambdas, etc. but requires heap allocation and not as fast as a function callback. DO NOT use from interrupt context, use a Task/Interrupt callback.

Parameters:: callback – The Delegate to be called
Return values:: bool – false if callback could not be queued

static inline unsigned getTaskCount()

Get number of tasks currently on queue.

Return values:: unsigned –

static inline unsigned getMaxTaskCount()

Get maximum number of tasks seen on queue at any one time.

Note

If return value is higher than maximum task queue TASK_QUEUE_LENGTH then the queue has overflowed at some point and tasks have been left un-executed.

Return values:: unsigned –