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

typedef void (*TaskCallback32)(uint32_t param)

Task callback function type, uint32_t parameter.

Note
Callback code does not need to be in IRAM

typedef void (*TaskCallback)(void *param)

Task callback function type, void* parameter.

Note
Callback code does not need to be in IRAM

typedef Delegate<void()> TaskDelegate

Task Delegate callback type.

typedef TaskDelegate SystemReadyDelegate

Handler function for system ready.

Enums

enum CpuFrequency

CPU Frequency.

Values:

eCF_80MHz = 80

CPU 80MHz.

eCF_160MHz = 160

CPU 160MHz.

enum DeepSleepOptions

Deep sleep options.

Values:

eDSO_RF_CAL_BY_INIT_DATA = 0

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

eDSO_RF_CAL_ALWAYS = 1

RF_CAL after deep-sleep wake up, there will be large current.

eDSO_RF_CAL_NEVER = 2

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

eDSO_DISABLE_RF

=

4


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

enum SystemState

System state.

Values:

eSS_None

System state unknown.

eSS_Intializing

System initialising.

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 implented by classes to support on-ready callback.

Subclassed by WDTClass, WifiSniffer

Public Functions

virtual ~ISystemReadyHandler()
virtual void onSystemReady() = 0

Handle system ready events.

class SystemClass
#include <System.h>

System class.

Public Functions

SystemClass()
bool isReady()

Check if system ready.

Return Value
  • 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

void setCpuFrequency(CpuFrequency freq)

Set the CPU frequency.

Parameters
  • freq: Frequency to set CPU

CpuFrequency getCpuFrequency()

Get the CPU frequency.

Return Value
  • CpuFrequency: The frequency of the CPU

bool deepSleep(uint32_t timeMilliseconds, DeepSleepOptions options = eDSO_RF_CAL_BY_INIT_DATA)

Enter deep sleep mode.

Parameters
  • timeMilliseconds: Quantity of milliseconds to remain in deep sleep mode
  • options: Deep sleep options

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

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 Value
  • bool: true on success

static 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 Value
  • 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 Value
  • bool: false if callback could not be queued

static unsigned getTaskCount()

Get number of tasks currently on queue.

Return Value
  • unsigned:

static 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 Value
  • unsigned: