Base

Copyright 2017-2023 Moddable Tech, Inc.
Revised: August 16, 2023

Table of Contents

• Timer
• Time
• Debug
• UUID
• deepEqual
• structuredClone
• Instrumentation
• Console
• CLI
• Worker

class Timer

• Source code: timer
• Relevant Examples: timers

The Timer class provides both time-based callbacks and a delay function.

import Timer from "timer";

Timer.set(callback[, interval, repeat])

The set function is used to request a function be called once after a certain period.

An immediate timer is called on the next cycle through the run loop. To set an immediate timer, call set with a single argument.

Timer.set(id => trace("immediate fired\n"));

A one shot timer is called once after a specified number of milliseconds. If the number of milliseconds is zero, a one shot timer is equivalent to an immediate timer.

Timer.set(id => trace("one shot fired\n"), 1000);

Calling set with a repeat is equivalent to a repeating timer with the first callback triggered after the interval.

Timer.set(id => trace("repeat fired\n"), 1000, 100);

The callback function receives the timer id as the first argument.

Timer.repeat(callback, interval)

A repeating timer is called continuously until stopped using the Timer.clear function.

Timer.repeat(id => trace("repeat fired\n"), 1000);

The callback function receives the timer id as the first argument.

Timer.schedule(id [, interval[, repeat]])

The schedule function is used to reschedule an existing timer.

If called with an interval but no repeat, the timer behaves like a one shot timer created with Timer.set. If called with both an interval and repeat, it behaves like a repeating timer created with Timer.set with both interval and repeat arguments. If called with neither interval nor repeat arguments, the timer is unscheduled and will not trigger until rescheduled using Timer.schedule.

In the following example, the callback function is triggered twice at one second intervals and then rescheduled to once every two seconds.

let state = 0;
Timer.repeat(id => {
	if (0 == state)
		state = 1;
	else if (1 == state) {
		state = 2;
		Timer.schedule(id, 2000, 2000);
	}
}, 1000);

Note: If the next trigger time is unknown, unscheduling a timer is preferred to scheduling for a long time in the future. Unscheduling and rescheduling a timer can more efficient than clearing a timer and later allocating a new one.

Timer.clear(id)

The clear function cancels a timer. The Timer.set and Timer.repeat functions returns the ID for a timer, which is then passed to clear.

let aTimer = Timer.set(id => trace("one shot\n"), 1000);
Timer.clear(aTimer);

Note: Immediate and one shot timers are automatically cleared after invoking their callback function. There is no need to call clear except to cancel the timer before it fires.

Note: If Timer.clear is passed a value of undefined or null for the ID, no exception is generated.

Timer.delay(ms)

The delay function delays execution for the specified number of milliseconds.

Timer.delay(500);	// delay 1/2 second

class Time

• Source code: time
• Source code: time
• Relevant Examples: sntp, ntpclient, ios-time-sync

The Time class provides time functions and a tick counter.

import Time from "time";

Time.set(seconds)

The set function sets the system time. The seconds argument corresponds to the number of seconds elapsed since January 1, 1970, i.e. Unix time.

timezone property

The timezone property is set to the time zone offset in seconds from UTC.

Time.timezone = +9 * 60 * 60;	// Set time zone to UTC+09:00

dst property

The dst property is set to the daylight saving time (DST) offset in seconds.

Time.dst = 60 * 60;	// Set DST

ticks property

The ticks property returns the value of a millisecond counter. The value returned does not correspond to the time of day. The milliseconds are used to calculate time differences.

const start = Time.ticks;
for (let i = 0; i < 1000; i++)
	;
const stop = Time.ticks;
trace(`Operation took ${Time.delta(start, stop)} milliseconds\n`);

On devices that supports multiple concurrent JavaScript virtual machines (for example, using Workers), the clock used to determine the value of the ticks property is the same across all virtual machines. This allows tick values created in one machine to be compared with values from another.

The range of the value depends on the host. On most microcontrollers, the value is a signed 32-bit integer. On the simulator, it is a positive 64-bit floating point value. To determine the difference between two ticks values, use Time.delta() which is guaranteed to give a correct result for the host.

Time.delta(start[, end])

The delta function calculates the difference between two values returned by Time.ticks. It is guaranteed to return a correct result even when the value rolls over. If the optional end argument is omitted the current value of Time.ticks is used.

microseconds property (optional)

The microseconds property returns the value of a microseconds counter. The value returned does not correspond to the time of day. The microseconds are used to calculate time differences.

To use the microseconds property, include its manifest in the project manifest:

	"include": [
		...
		"$(MODDABLE)/modules/base/microseconds/manifest.json",
	],

The microseconds property is used in the same way as the ticks property. Like the ticks property, a single time source is used when there multiple concurrent virtual machines. The range of the microseconds property is a 64-bit floating point value.

Unlike Time.ticks, the values returned by Time.microseconds may always be subtracted from one another to calculate intervals.

const start = Time.microseconds;
for (let i = 0; i < 1000; i++)
	;
const stop = Time.microseconds;
trace(`Operation took ${stop - start} microseconds\n`);

Note: Not all hosts implement microseconds. Hosts that do not implement microseconds generate an error at build time.

class Debug

• Source code: debug

The Debug class provides functions that are useful during the development process.

import Debug from "debug";

Debug.gc([enable])

The gc function can be used to turn the JavaScript garbage collector on and off, as well as to run the garbage collector on-demand.

Calling Debug.gc with no arguments runs the garbage collector immediately.

Debug.gc();

Calling Debug.gc with a single boolean argument enables or disables the garbage collector.

Debug.gc(true)	// enable garbage collector
Debug.gc(false);	// disable garbage collector

class UUID

• Source code: uuid

The UUID class provides a single function to generate a UUID string.

import UUID from "uuid";

Note: Generating a truly unique UUID requires that the device running this function have a unique MAC address and the valid time. Neither of these is guaranteed on all microcontrollers. For production software release, check your device configuration.

UUID()

The UUID function returns a new UUID formatted as a string.

let value = UUID();	// 1080B49C-59FC-4A32-A38B-DE7E80117842

function deepEqual(a, b [,options])

• Source code: deepEqual
• Tests: deepEqual

The deepEqual function implements a deep comparison between two JavaScript object.

import deepEqual from "deepEqual";

There is no standard algorithm for deeply comparing two objects in JavaScript, and there are many possible correct approaches. The Moddable SDK adopts the behavior of assert.deepEqual and assert.deepStrictEqual from Node.js for its implementation of deepEqual.

The deepEqual function has an optional third parameter, an options object. By default the deepEqual comparison is not-strict, similar to using == for comparisons. Passing {strict: true} for the options object uses strict comparison, similar to using === for comparisons.

const a = {a: 1, b: 0, c: "str"};
const b = {a: 1, b: "0", c: "str"};
deepEqual(a, b);		// true
deepEqual(a, b, {strict: true});		// false

The known differences between the Moddable SDK implementation and Node.js will not impact most uses:

• WeakMap and WeakSet using read-only objects as keys
• XS does not call valueOf to compare boxed primitives

function structuredClone(object[, transferables])

• Source code: structuredClone
• Tests: structuredClone

The structuredClone function creates a deep copy of a JavaScript object.

import structuredClone from "structuredClone";

The structuredClone function in the Moddable SDK implements the algorithm defined by WHATWG for the web platform as much as practical, including circular references and the transferables option.

const a = {a: 1, b: Uint8Array.of(1, 2, 3,)}
const aCopy = structuredClone(a);

The Moddable SDK implementation of structuredClone implements all supported types that are part of the JavaScript language standard. It does not, of course, clone object types that are part of the web platform and not present on embedded systems such as DOMException.

class Instrumentation

• Source code: instrumentation
• Relevant Examples: instrumentation, xsuse

The Instrumentation class returns statistics on the behavior of the runtime, including memory use, open file count, and rendering frame rate.

import Instrumentation from "instrumentation";

get(what)

The get function returns the value of the instrumented item at the index specified by the what parameter. Instrumented items are consecutively numbered starting at index 1.

let pixelsDrawn = Instrumentation.get(1);

The index of instrumentation items depends on the host and varies between different devices based on the supported features. Use Instrumentation.map() to determine the index of a specific instrumentation on the running host.

map(name)

The map function returns the instrumentation index for a name.

let pixelsDrawnIndex = Instrumentation.map("Pixels Drawn");
let pixelsDrawn = Instrumentation.get(pixelsDrawnIndex);

If the instrumentation item named is unavailable, map returns undefined.

name(index)

The name function returns the name of the instrumentation item at the specified index. It can be used to iterate through all available instrumentation items.

for (let i = 1; true; i++) {
	const name = Instrumentation.name(i);
	if (!name)
		break;
	trace(`${name}: ${Instrumentation.get(i)}\n`);
}

Instrumentation items

The table below describes the instrumented items that are available. The following instrumented items are reset at one second intervals: Pixels Drawn, Frames Drawn, Poco Display List Used, Piu Command List Used, Network Bytes Read, Network Bytes Written, and Garbage Collection Count.

class Console

• Source code: console
• Relevant Examples: console

The Console class implements a serial terminal for debugging and diagnostic purposes. The Console module uses CLI modules to implement the terminal commands.

class CLI

• Source code: cli
• Relevant Examples: console, telnet

The CLI class is a plug-in interface for commands used in a command line interface. CLI classes implement commands for use by the Console module (serial command line) and Telnet module (network command line).

class Worker

See the Worker documentation for information about the Worker class.