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

CPU Frequency.

Values:

enumerator eCF_80MHz

CPU 80MHz.

enumerator eCF_160MHz

CPU 160MHz.

enumerator eCF_240MHz

CPU 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.

Returns

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 void setCpuFrequency(CpuFrequency freq)

Set the CPU frequency.

Parameters

freq – Frequency to set CPU

inline CpuFrequency getCpuFrequency()

Get the CPU frequency.

Returns

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

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.

Returns

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)

Returns

bool – false if callback could not be queued

static inline bool queueCallback(TaskCallback callback, void *param = nullptr)

Queue a deferred callback, with optional void* parameter.

static inline 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

Returns

bool – false if callback could not be queued

static inline unsigned getTaskCount()

Get number of tasks currently on queue.

Returns

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.

Returns

unsigned