Timers

Github Repo C Header C source JS source
cesanta/mongoose-os mgos_timers.h mgos_timers.c api_timer.js

Mongoose OS supports two types of timers: software timers and hardware timers.

  • Software timers. Implemented as Mongoose library events, in software. Timer callback is called in a Mongoose task context. Frequency is specified in milliseconds. Number of software timers is not limited. Timer intervals cannot be short - limited by the underlying task scheduling. For example, if you want a very frequent sensor reading, like thousand readings a second, use hardware timer instead. Both C and JavaScript API is available.
  • Hardware timers. Implemented in hardware. Timer callback is executed in the ISR context, therefore it can do a limited set of actions. Number of hardware timers is limied: (ESP8266: 1, ESP32: 4, CC32xx: 4). Frequency is specified in microseconds. Only C API is present, because calling to JS requires switching to Mongoose task context.

Usage example:

#include "mgos_app.h"
#include "mgos_system.h"
#include "mgos_timers.h"

static void my_timer_cb(void *arg) {
  bool val = mgos_gpio_toggle(mgos_sys_config_get_pins_led());
  LOG(LL_INFO, ("uptime: %.2lf", mgos_uptime()));
  (void) arg;
}

enum mgos_app_init_result mgos_app_init(void) {
  mgos_set_timer(1000, MGOS_TIMER_REPEAT, my_timer_cb, NULL);
  return MGOS_APP_INIT_SUCCESS;
}

(*timer_callback)

typedef void (*timer_callback)(void *param);

Timer callback

mgos_set_timer

mgos_timer_id mgos_set_timer(int msecs, int flags, timer_callback cb,
                             void *cb_arg);

Setup a timer with msecs timeout and cb as a callback.

flags is a bitmask, currently there's only one flag available: MGOS_TIMER_REPEAT (see above). arg is a parameter to pass to cb. Return numeric timer ID.

Note that this is a software timer, with fairly low accuracy and high jitter. However, number of software timers is not limited. If you need intervals < 10ms, use mgos_set_hw_timer.

Example:

static void my_timer_cb(void *arg) {
  bool val = mgos_gpio_toggle(mgos_sys_config_get_pins_led());
  LOG(LL_INFO, ("uptime: %.2lf", mgos_uptime()));
  (void) arg;
}

enum mgos_app_init_result mgos_app_init(void) {
  mgos_set_timer(1000, MGOS_TIMER_REPEAT, my_timer_cb, NULL);
  return MGOS_APP_INIT_SUCCESS;
}

mgos_set_hw_timer

mgos_timer_id mgos_set_hw_timer(int usecs, int flags, timer_callback cb,
                                void *cb_arg);

Setup a hardware timer with usecs timeout and cb as a callback.

This is similar to mgos_set_timer, but can be used for shorter intervals (note that time unit is microseconds).

Number of hardware timers is limited (ESP8266: 1, ESP32: 4, CC32xx: 4).

Callback is executed in ISR context, with all the implications of that.

mgos_clear_timer

void mgos_clear_timer(mgos_timer_id id);

Disable timer with a given timer ID.

mgos_uptime

double mgos_uptime(void);

Get number of seconds since last reboot

mgos_strftime

int mgos_strftime(char *s, int size, char *fmt, int time);

Format time according to a strftime()-conformant format. Write the result into the s,size buffer. Return resulting string length.

JS API


Timer.set

Timer.set(milliseconds, flags, handler, userdata)

Setup timer with milliseconds timeout and handler as a callback. flags can be either 0 or Timer.REPEAT. In the latter case, the call will be repeated indefinitely (but can be cancelled with Timer.del()), otherwise it's a one-off.

Return value: numeric timer ID.

Example:

// Call every second
Timer.set(1000, Timer.REPEAT, function() {
  let value = GPIO.toggle(2);
  print(value ? 'Tick' : 'Tock');
}, null);

Timer.now

Timer.now()

Return current time as double value (in secounds), UNIX epoch (seconds since 1970).

Timer.del

Timer.del(id)

Cancel previously installed timer.

Timer.fmt

Timer.fmt(fmt, time)

Formats the time 'time' according to the strftime-like format specification 'fmt'. The strftime reference can be found e.g. here. Example:

let now = Timer.now();
let s = Timer.fmt("Now it's %I:%M%p.", now);
print(s); // Example output: "Now it's 12:01AM."
edit this doc