Bangle.js Software Reference

The filename of the JavaScript that is currently executing.

If load has been called with a filename (eg load("myfile.js")) then __FILE__ is set to that filename. Otherwise (eg load()) or immediately after booting, __FILE__ is not set.

Get the analogue value of the given pin.

This is different to Arduino which only returns an integer between 0 and 1023

However only pins connected to an ADC will work (see the datasheet)

Note: if you didn't call pinMode beforehand then this function will also reset pin's state to "analog"

Note: Jolt.js motor driver pins with analog inputs are scaled with a potential divider, and so those pins return a number which is the actual voltage.

Set the analog Value of a pin. It will be output using PWM.

Objects can contain:

• freq - pulse frequency in Hz, e.g. analogWrite(A0,0.5,{ freq : 10 }); - specifying a frequency will force PWM output, even if the pin has a DAC
• soft - boolean, If true software PWM is used if hardware is not available.
• forceSoft - boolean, If true software PWM is used even if hardware PWM or a DAC is available

On nRF52-based devices (Puck.js, Pixl.js, MDBT42Q, etc) hardware PWM runs at 16MHz, with a maximum output frequency of 4MHz (but with only 2 bit (0..3) accuracy). At 1Mhz, you have 4 bits (0..15), 1kHz = 14 bits and so on.

Note: if you didn't call pinMode beforehand then this function will also reset pin's state to "output"

A variable containing the arguments given to the function:

function hello() {
  console.log(arguments.length, JSON.stringify(arguments));
}
hello()        // 0 []
hello("Test")  // 1 ["Test"]
hello(1,2,3)   // 3 [1,2,3]

Note: Due to the way Espruino works this is doesn't behave exactly the same as in normal JavaScript. The length of the arguments array will never be less than the number of arguments specified in the function declaration: (function(a){ return arguments.length; })() == 1. Normal JavaScript interpreters would return 0 in the above case.

Decode the supplied base64 string into a normal string

Note: This is not available in devices with low flash memory

The Bluetooth Serial port - used when data is sent or received over Bluetooth Smart on nRF51/nRF52 chips.

Note: This is only available in devices with Bluetooth LE capability

Encode the supplied string (or array) into a base64 string

Note: This is not available in devices with low flash memory

Change the Interval on a callback created with setInterval, for example:

var id = setInterval(function () { print('foo'); }, 1000); // every second

changeInterval(id, 1500); // now runs every 1.5 seconds

This takes effect immediately and resets the timeout, so in the example above, regardless of when you call changeInterval, the next interval will occur 1500ms after it.

Clear the Interval that was created with setInterval, for example:

var id = setInterval(function () { print('foo'); }, 1000);

clearInterval(id);

If no argument is supplied, all timeouts and intervals are stopped.

To avoid accidentally deleting all Intervals, if a parameter is supplied but is undefined then an Exception will be thrown.

Clear the Timeout that was created with setTimeout, for example:

var id = setTimeout(function () { print('foo'); }, 1000);

clearTimeout(id);

If no argument is supplied, all timeouts and intervals are stopped.

To avoid accidentally deleting all Timeouts, if a parameter is supplied but is undefined then an Exception will be thrown.

Clear the Watch that was created with setWatch. If no parameter is supplied, all watches will be removed.

To avoid accidentally deleting all Watches, if a parameter is supplied but is undefined then an Exception will be thrown.

Convert any groups of characters of the form '%ZZ', into characters with hex code '0xZZ'

Note: This is not available in devices with low flash memory

Pulse the pin with the value for the given time in milliseconds. It uses a hardware timer to produce accurate pulses, and returns immediately (before the pulse has finished). Use digitalPulse(A0,1,0) to wait until a previous pulse has finished.

e.g. digitalPulse(A0,1,5); pulses A0 high for 5ms. digitalPulse(A0,1,[5,2,4]); pulses A0 high for 5ms, low for 2ms, and high for 4ms

Note: if you didn't call pinMode beforehand then this function will also reset pin's state to "output"

digitalPulse is for SHORT pulses that need to be very accurate. If you're doing anything over a few milliseconds, use setTimeout instead.

Get the digital value of the given pin.

Note: if you didn't call pinMode beforehand then this function will also reset pin's state to "input"

If the pin argument is an array of pins (e.g. [A2,A1,A0]) the value returned will be an number where the last array element is the least significant bit, for example if A0=A1=1 and A2=0, digitalRead([A2,A1,A0]) == 0b011

If the pin argument is an object with a read method, the read method will be called and the integer value it returns passed back.

Set the digital value of the given pin.

digitalWrite(LED1, 1); // light LED1
digitalWrite([LED1,LED2,LED3], 0b101); // lights LED1 and LED3

Note: if you didn't call pinMode(pin, ...) or Pin.mode(...) beforehand then this function will also reset pin's state to "output"

If pin argument is an array of pins (e.g. [A2,A1,A0]) the value argument will be treated as an array of bits where the last array element is the least significant bit.

In this case, pin values are set least significant bit first (from the right-hand side of the array of pins). This means you can use the same pin multiple times, for example digitalWrite([A1,A1,A0,A0],0b0101) would pulse A0 followed by A1.

In 2v22 and later firmwares, using a boolean for the value will set all pins in the array to the same value, eg digitalWrite(pins, value?0xFFFFFFFF:0). Previously digitalWrite with a boolean behaved like digitalWrite(pins, value?1:0) and would only set the first pin.

If the pin argument is an object with a write method, the write method will be called with the value passed through.

Output current interpreter state in a text form such that it can be copied to a new device

Espruino keeps its current state in RAM (even if the function code is stored in Flash). When you type dump() it dumps the current state of code in RAM plus the hardware state, then if there's code saved in flash it writes "// Code saved with E.setBootCode" and dumps that too.

Note: 'Internal' functions are currently not handled correctly. You will need to recreate these in the onInit function.

Note: This is not available in devices with low flash memory

Should Espruino echo what you type back to you? true = yes (Default), false = no. When echo is off, the result of executing a command is not returned. Instead, you must use 'print' to send output.

Fill the console with the contents of the given function, so you can edit it.

NOTE: This is a convenience function - it will not edit 'inner functions'. For that, you must edit the 'outer function' and re-execute it.

Note: This is not available in devices with low flash memory

Convert a string with any character not alphanumeric or - _ . ! ~ * ' ( ) converted to the form %XY where XY is its hexadecimal representation

Note: This is not available in devices with low flash memory

Evaluate a string containing JavaScript code

Return the current mode of the given pin. See pinMode for more information on returned values.

Note: This is not available in devices with low flash memory

Get the serial number of this board

Note: This is not available in devices with low flash memory

Return the current system time in Seconds (as a floating point number)

A reference to the global scope, where everything is defined.

global is used in Node.js. Consider using the identical globalThis as it was introduced in the ECMAScript spec.

A reference to the global scope, where everything is defined.

This is identical to global but was introduced in the ECMAScript spec.

DEPRECATED - this will be removed in subsequent versions of Espruino

Note: This is not available in devices with low flash memory

Is the parameter a finite number or not? If needed, the parameter is first converted to a number.

Whether the x is NaN (Not a Number) or not

Restart and load the program out of flash - this has an effect similar to completely rebooting Espruino (power off/power on), but without actually performing a full reset of the hardware.

This command only executes when the Interpreter returns to the Idle state - for instance a=1;load();a=2; will still leave 'a' as undefined (or what it was set to in the saved program).

Espruino will resume from where it was when you last typed save(). If you want code to be executed right after loading (for instance to initialise devices connected to Espruino), add an init event handler to E with

E.on('init',
function() { ... your_code ... });

If you specify a filename in the argument then that file will be loaded from Storage after reset in much the same way as calling reset() then eval(require("Storage").read(filename))

A loopback serial device. Data sent to LoopbackA comes out of LoopbackB and vice versa

A loopback serial device. Data sent to LoopbackA comes out of LoopbackB and vice versa

DEPRECATED - this will be removed in subsequent versions of Espruino

Note: This is not available in devices with low flash memory

Convert a string representing a number into an float

Convert a string representing a number into an integer

Read 16 bits of memory at the given location - DANGEROUS!

Read 32 bits of memory at the given location - DANGEROUS!

Read 8 bits of memory at the given location - DANGEROUS!

Set the mode of the given pin.

• auto/undefined - Don't change state, but allow digitalWrite/etc to automatically change state as appropriate
• analog - Analog input
• input - Digital input
• input_pullup - Digital input with internal ~40k pull-up resistor
• input_pulldown - Digital input with internal ~40k pull-down resistor
• output - Digital output
• opendrain - Digital output that only ever pulls down to 0v. Sending a logical 1 leaves the pin open circuit
• opendrain_pullup - Digital output that pulls down to 0v. Sending a logical 1 enables internal ~40k pull-up resistor
• af_output - Digital output from built-in peripheral

• af_opendrain - Digital output from built-in peripheral that only ever pulls down to 0v. Sending a logical 1 leaves the pin open circuit

  Note: digitalRead/digitalWrite/etc set the pin mode automatically unless pinMode has been called first. If you want digitalRead/etc to set the pin mode automatically after you have called pinMode, simply call it again with no mode argument (pinMode(pin)), auto as the argument (

  pinMode(pin,
  "auto")

  ), or with the 3rd 'automatic' argument set to true (

  pinMode(pin,
  "output", true)

  ).

Write 16 bits of memory at the given location - VERY DANGEROUS!

Write 32 bits of memory at the given location - VERY DANGEROUS!

Write 8 bits of memory at the given location - VERY DANGEROUS!

Print the supplied string(s) to the console

Note:* If you're connected to a computer (not a wall adaptor) via USB but *you are not running a terminal app then when you print data Espruino may pause execution and wait until the computer requests the data it is trying to print.

Load the given module, and return the exported functions and variables.

For example:

var s = require("Storage");
s.write("test", "hello world");
print(s.read("test"));
// prints "hello world"

Check out the page on Modules for an explanation of what modules are and how you can use them.

Reset the interpreter - clear program memory in RAM, and do not load a saved program from flash. This does NOT reset the underlying hardware (which allows you to reset the device without it disconnecting from USB).

This command only executes when the Interpreter returns to the Idle state - for instance a=1;reset();a=2; will still leave 'a' as undefined.

The safest way to do a full reset is to hit the reset button.

If reset() is called with no arguments, it will reset the board's state in RAM but will not reset the state in flash. When next powered on (or when load() is called) the board will load the previously saved code.

Calling reset(true) will cause all saved code in flash memory to be cleared as well.

The first Serial (USART) port

Note: This is only available in devices with more than \2 \1 peripherals

When Espruino is busy, set the pin specified here high. Set this to undefined to disable the feature.

Note: This is not available in devices with low flash memory

Call the function (or evaluate the string) specified REPEATEDLY after the timeout in milliseconds.

For instance:

setInterval(function () {
  console.log("Hello World");
}, 1000);
// or
setInterval('console.log("Hello World");', 1000);
// both print 'Hello World' every second

You can also specify extra arguments that will be sent to the function when it is executed. For example:

setInterval(function (a,b) {
  console.log(a+" "+b);
}, 1000, "Hello", "World");
// prints 'Hello World' every second

If you want to stop your function from being called, pass the number that was returned by setInterval into the clearInterval function.

Note: If setDeepSleep(true) has been called and the interval is greater than 5 seconds, Espruino may execute the interval up to 1 second late. This is because Espruino can only wake from deep sleep every second - and waking early would cause Espruino to waste power while it waited for the correct time.

When Espruino is asleep, set the pin specified here low (when it's awake, set it high). Set this to undefined to disable the feature.

Please see http://www.espruino.com/Power+Consumption for more details on this.

Note: This is not available in devices with low flash memory

Set the current system time in seconds (time can be a floating point value).

This is used with getTime, the time reported from setWatch, as well as when using new Date().

Date.prototype.getTime() reports the time in milliseconds, so you can set the time to a Date object using:

setTime((new Date("Tue, 19 Feb 2019 10:57")).getTime()/1000)

To set the timezone for all new Dates, use E.setTimeZone(hours).

Call the function (or evaluate the string) specified ONCE after the timeout in milliseconds.

For instance:

setTimeout(function () {
  console.log("Hello World");
}, 1000);
// or
setTimeout('console.log("Hello World");', 1000);
// both print 'Hello World' after a second

You can also specify extra arguments that will be sent to the function when it is executed. For example:

setTimeout(function (a,b) {
  console.log(a+" "+b);
}, 1000, "Hello", "World");
// prints 'Hello World' after 1 second

If you want to stop the function from being called, pass the number that was returned by setTimeout into the clearTimeout function.

Note: If setDeepSleep(true) has been called and the interval is greater than 5 seconds, Espruino may execute the interval up to 1 second late. This is because Espruino can only wake from deep sleep every second - and waking early would cause Espruino to waste power while it waited for the correct time.

Call the function specified when the pin changes. Watches set with setWatch can be removed using clearWatch.

If the options parameter is an object, it can contain the following information (all optional):

{
   // Whether to keep producing callbacks, or remove the watch after the first callback
   repeat: true/false(default),
   // Trigger on the rising or falling edge of the signal. Can be a string, or 1='rising', -1='falling', 0='both'
   edge:'rising'(default for built-in buttons)/'falling'/'both'(default for pins),
   // Use software-debouncing to stop multiple calls if a switch bounces
   // This is the time in milliseconds to wait for bounces to subside, or 0 to disable
   debounce:10 (0 is default for pins, 25 is default for built-in buttons),
   // Advanced: If the function supplied is a 'native' function (compiled or assembly)
   // setting irq:true will call that function in the interrupt itself
   irq : false(default)
   // Advanced: If specified, the given pin will be read whenever the watch is called
   // and the state will be included as a 'data' field in the callback (`debounce:0` is required)
   data : pin
   // Advanced: On Nordic devices, a watch may be 'high' or 'low' accuracy. By default low
   // accuracy is used (which is better for power consumption), but this means that
   // high speed pulses (less than 25us) may not be reliably received. Setting hispeed=true
   // allows for detecting high speed pulses at the expense of higher idle power consumption
   hispeed : true
}

The function callback is called with an argument, which is an object of type {state:bool, time:float, lastTime:float}.

• state is whether the pin is currently a 1 or a 0
• time is the time in seconds at which the pin changed state
• lastTime is the time in seconds at which the pin last changed state. When using edge:'rising' or edge:'falling', this is not the same as when the function was last called.
• data is included if data:pin was specified in the options, and can be used for reading in clocked data. It will only work if debounce:0 is used

For instance, if you want to measure the length of a positive pulse you could use

setWatch(function(e) { console.log(e.time-e.lastTime); }, BTN, {
repeat:true, edge:'falling' });

Internally, an interrupt writes the time of the pin's state change into a queue with the exact time that it happened, and the function supplied to setWatch is executed only from the main message loop. However, if the callback is a native function void (bool state) then you can add irq:true to options, which will cause the function to be called from within the IRQ. When doing this, interrupts will happen on both edges and there will be no debouncing.

Note: if you didn't call pinMode beforehand then this function will reset pin's state to "input"

Note: The STM32 chip (used in the Espruino Board and Pico) cannot watch two pins with the same number - e.g. A0 and B0.

Note: On nRF52 chips (used in Puck.js, Pixl.js, MDBT42Q) setWatch disables the GPIO output on that pin. In order to be able to write to the pin again you need to disable the watch with clearWatch.

Shift an array of data out using the pins supplied least significant bit first, for example:

// shift out to single clk+data
shiftOut(A0, { clk : A1 }, [1,0,1,0]);

// shift out a whole byte (like software SPI)
shiftOut(A0, { clk : A1, repeat: 8 }, [1,2,3,4]);

// shift out via 4 data pins
shiftOut([A3,A2,A1,A0], { clk : A4 }, [1,2,3,4]);

options is an object of the form:

{
  clk : pin, // a pin to use as the clock (undefined = no pin)
  clkPol : bool, // clock polarity - default is 0 (so 1 normally, pulsing to 0 to clock data in)
  repeat : int, // number of clocks per array item
}

Each item in the data array will be output to the pins, with the first pin in the array being the MSB and the last the LSB, then the clock will be pulsed in the polarity given.

repeat is the amount of times shift data out for each array item. For instance we may want to shift 8 bits out through 2 pins - in which case we need to set repeat to 4.

A simple VT100 terminal emulator.

When data is sent to the Terminal object, Graphics.getInstance() is called and if an instance of Graphics is found then characters are written to it.

Note: This is only available in devices with VT100 terminal emulation enabled (Pixl.js only)

Output debugging information

Note: This is not included on boards with low amounts of flash memory, or the Espruino board.

Note: This is not available in devices with low flash memory

The Bangle.js's vibration motor.

Note: This is only available in Bangle.js smartwatches

This is the built-in JavaScript class for arrays.

Arrays can be defined with [], new Array(), or

new
Array(length)

Create an Array. Either give it one integer argument (>=0) which is the length of the array, or any number of arguments

Create a new array, containing the elements from this one and any arguments, if any argument is an array then those elements will be added.

Note: This is not available in devices with low flash memory

Return 'true' if the callback returns 'true' for every element in the array

Note: Do not modify the array you're iterating over from inside the callback (a.every(()=>a.push(0))). It will cause non-spec-compliant behaviour.

Fill this array with the given value, for every index >= start and < end

Note: This is not available in devices with low flash memory

Return an array which contains only those elements for which the callback function returns 'true'

Note: Do not modify the array you're iterating over from inside the callback (a.filter(()=>a.push(0))). It will cause non-spec-compliant behaviour.

Return the array element where function returns true, or undefined if it doesn't returns true for any element.

["Hello","There","World"].find(a=>a[0]=="T")
// returns "There"

Note: Do not modify the array you're iterating over from inside the callback (a.find(()=>a.push(0))). It will cause non-spec-compliant behaviour.

Note: This is not available in devices with low flash memory

Return the array element's index where function returns true, or -1 if it doesn't returns true for any element.

["Hello","There","World"].findIndex(a=>a[0]=="T")
// returns 1

Note: Do not modify the array you're iterating over from inside the callback (a.findIndex(()=>a.push(0))). It will cause non-spec-compliant behaviour.

Note: This is not available in devices with low flash memory

Executes a provided function once per array element.

Note: Do not modify the array you're iterating over from inside the callback (a.forEach(()=>a.push(0))). It will cause non-spec-compliant behaviour.

Return true if the array includes the value, false otherwise

Note: This is not available in devices with low flash memory

Return the index of the value in the array, or -1

Returns true if the provided object is an array

Join all elements of this array together into one string, using 'separator' between them. e.g. [1,2,3].join(' ')=='1 2 3'

Find the length of the array

Return an array which is made from the following:

A.map(function) =
[function(A[0]), function(A[1]), ...]

Note: Do not modify the array you're iterating over from inside the callback (a.map(()=>a.push(0))). It will cause non-spec-compliant behaviour.

Remove and return the value on the end of this array.

This is the opposite of [1,2,3].shift(), which removes an element from the beginning of the array.

Push a new value onto the end of this array'

This is the opposite of [1,2,3].unshift(0), which adds one or more elements to the beginning of the array.

Execute previousValue=initialValue and then

previousValue =
callback(previousValue, currentValue, index, array)

Note: Do not modify the array you're iterating over from inside the callback (a.reduce(()=>a.push(0))). It will cause non-spec-compliant behaviour.

Note: This is not available in devices with low flash memory

Reverse all elements in this array (in place)

Note: This is not available in devices with low flash memory

Remove and return the first element of the array.

This is the opposite of [1,2,3].pop(), which takes an element off the end.

Note: This is not available in devices with low flash memory

Return a copy of a portion of this array (in a new array)

Return 'true' if the callback returns 'true' for any of the elements in the array

Note: Do not modify the array you're iterating over from inside the callback (a.some(()=>a.push(0))). It will cause non-spec-compliant behaviour.

Do an in-place quicksort of the array

Note: Do not modify the array you're iterating over from inside the callback (a.sort(()=>a.push(0))). It will cause non-spec-compliant behaviour.

Note: This is not available in devices with low flash memory

Both remove and add items to an array

Convert the Array to a string

Add one or more items to the start of the array, and return its new length.

This is the opposite of [1,2,3].push(4), which puts one or more elements on the end.

Note: This is not available in devices with low flash memory

This is the built-in JavaScript class for array buffers.

If you want to access arrays of differing types of data you may also find DataView useful.

Create an Array Buffer object

The length, in bytes, of the ArrayBuffer

This is the built-in JavaScript class that is the prototype for:

• Uint8Array
• UintClamped8Array
• Int8Array
• Uint16Array
• Int16Array
• Uint24Array (Espruino-specific - not standard JS)
• Uint32Array
• Int32Array
• Float32Array
• Float64Array

If you want to access arrays of differing types of data you may also find DataView useful.

The buffer this view references

The length, in bytes, of the ArrayBufferView

The offset, in bytes, to the first byte of the view within the backing ArrayBuffer

Fill this array with the given value, for every index >= start and < end

Note: This is not available in devices with low flash memory

Return an array which contains only those elements for which the callback function returns 'true'

Note: This is not available in devices with low flash memory

Return the array element where function returns true, or undefined if it doesn't returns true for any element.

Note: This is not available in devices with low flash memory

Return the array element's index where function returns true, or -1 if it doesn't returns true for any element.

Note: This is not available in devices with low flash memory

Executes a provided function once per array element.

Return true if the array includes the value, false otherwise

Note: This is not available in devices with low flash memory

Return the index of the value in the array, or -1

Join all elements of this array together into one string, using 'separator' between them. e.g. [1,2,3].join(' ')=='1 2 3'

Return an array which is made from the following:

A.map(function) =
[function(A[0]), function(A[1]), ...]

Note: This returns an ArrayBuffer of the same type it was called on. To get an Array, use Array.map, e.g. [].map.call(myArray, x=>x+1)

Execute previousValue=initialValue and then

previousValue =
callback(previousValue, currentValue, index, array)

Note: This is not available in devices with low flash memory

Reverse the contents of this ArrayBufferView in-place

Note: This is not available in devices with low flash memory

Copy the contents of array into this one, mapping this[x+offset]=array[x];

Return a copy of a portion of this array (in a new array).

Note: This currently returns a normal Array, not an ArrayBuffer

Note: This is not available in devices with low flash memory

Do an in-place quicksort of the array

Note: This is not available in devices with low flash memory

Returns a smaller part of this array which references the same data (it doesn't copy it).

Note: This is not available in devices with low flash memory

Class containing utility functions for the Bangle.js Smart Watch

Accelerometer data available with {x,y,z,diff,mag} object as a parameter.

• x is X axis (left-right) in g
• y is Y axis (up-down) in g
• z is Z axis (in-out) in g
• diff is difference between this and the last reading in g
• mag is the magnitude of the acceleration in g

You can also retrieve the most recent reading with Bangle.getAccel().

Note: This is only available in Bangle.js smartwatches

Reads a register from the accelerometer

Note: On Espruino 2v06 and before this function only returns a number (cnt is ignored).

Note: This is only available in Bangle.js smartwatches

Emitted when a 'gesture' (fast movement) is detected, and a Tensorflow model is in storage in the ".tfmodel" file.

If a ".tfnames" file is specified as a comma-separated list of names, it will be used to decode gesture from a number into a string.

Note: This is only available in Bangle.js smartwatches

Returns the rectangle on the screen that is currently reserved for the app.

Note: This is only available in Bangle.js smartwatches

Has the backlight been turned on or off? Can be used to stop tasks that are no longer useful if want to see in sun screen only. Also see Bangle.isBacklightOn()

Note: This is only available in Bangle.js smartwatches

Use the piezo speaker to Beep for a certain time period and frequency

Note: This is only available in Bangle.js smartwatches

Use the vibration motor to buzz for a certain time period

Note: This is only available in Bangle.js smartwatches

Is the battery charging or not?

Note: This is only available in Bangle.js smartwatches

Read a register on the Magnetometer/Compass

Note: This is only available in Bangle.js smartwatches

Writes a register on the Magnetometer/Compass

Note: This is only available in Bangle.js smartwatches

Reads debug info. Exposes the current values of accHistoryIdx, accGestureCount, accIdleCount, pollInterval and others.

Please see the declaration of this function for more information (click the ==> link above this description)

Note: This is only available in Bangle.js smartwatches

Emitted when the touchscreen is dragged or released

The touchscreen extends past the edge of the screen and while x and y coordinates are arranged such that they align with the LCD's pixels, if your finger goes towards the edge of the screen, x and y could end up larger than 175 (the screen's maximum pixel coordinates) or smaller than 0. Coordinates from the touch event are clipped.

Note: This is only available in Bangle.js smartwatches

Draw any onscreen widgets that were loaded with Bangle.loadWidgets().

Widgets should redraw themselves when something changes - you'll only need to call drawWidgets if you decide to clear the entire screen with g.clear().

Note: This is only available in Bangle.js smartwatches

Has the watch been moved so that it is face-up, or not face up?

Note: This is only available in Bangle.js smartwatches

Emitted when a 'gesture' (fast movement) is detected

Note: This is only available in Bangle.js smartwatches

Get the most recent accelerometer reading. Data is in the same format as the Bangle.on('accel', event.

• x is X axis (left-right) in g
• y is Y axis (up-down) in g
• z is Z axis (in-out) in g
• diff is difference between this and the last reading in g (calculated by comparing vectors, not magnitudes)
• td is the elapsed
• mag is the magnitude of the acceleration in g

Note: This is only available in Bangle.js smartwatches

Get the most recent Magnetometer/Compass reading. Data is in the same format as the Bangle.on('mag', event.

Returns an {x,y,z,dx,dy,dz,heading} object

• x/y/z raw x,y,z magnetometer readings
• dx/dy/dz readings based on calibration since magnetometer turned on
• heading in degrees based on calibrated readings (will be NaN if magnetometer hasn't been rotated around 360 degrees).

Note: In 2v15 firmware and earlier the heading is inverted (360-heading). There's a fix in the bootloader which will apply a fix for those headings, but old apps may still expect an inverted value.

To get this event you must turn the compass on with Bangle.setCompassPower(1).

Note: This is only available in Bangle.js smartwatches

Get the last available GPS fix info (or undefined if GPS is off).

The fix info received is the same as you'd get from the Bangle.GPS event.

Note: This is only available in Bangle.js smartwatches

range is one of:

• undefined or '10min' - health data so far in this 10 minute block (eg. 9:00.00 - 9:09.59)
• 'last' - health data during the last 10 minute block
• 'day' - the health data so far for the day

getHealthStatus returns an object containing:

• movement is the 32 bit sum of all acc.diff readings since power on (and rolls over). It is the difference in accelerometer values as g*8192
• steps is the number of steps during this period
• bpm the best BPM reading from HRM sensor during this period
• bpmConfidence best BPM confidence (0-100%) during this period

Note: This is only available in Bangle.js smartwatches

The current LCD mode.

See Bangle.setLCDMode for examples.

Note: This is only available in Bangle.js smartwatches

• On platforms with an LCD of >=8bpp this is 222 x 104 x 2 bits
• Otherwise it's 119 x 56 x 1 bits

Note: This is only available in Bangle.js smartwatches

Return the current state of options as set by Bangle.setOptions

Note: This is only available in Bangle.js smartwatches

Returns the current amount of steps recorded by the step counter

Note: This is only available in Bangle.js smartwatches

GPS data, as an object. Contains:

{ "lat": number,      // Latitude in degrees
  "lon": number,      // Longitude in degrees
  "alt": number,      // altitude in M
  "speed": number,    // Speed in kph
  "course": number,   // Course in degrees
  "time": Date,       // Current Time (or undefined if not known)
  "satellites": 7,    // Number of satellites
  "fix": 1            // NMEA Fix state - 0 is no fix
  "hdop": number,     // Horizontal Dilution of Precision
}

If a value such as lat is not known because there is no fix, it'll be NaN.

hdop is a value from the GPS receiver that gives a rough idea of accuracy of lat/lon based on the geometry of the satellites in range. Multiply by 5 to get a value in meters. This is just a ballpark estimation and should not be considered remotely accurate.

To get this event you must turn the GPS on with Bangle.setGPSPower(1).

Note: This is only available in Bangle.js smartwatches

Raw NMEA GPS / u-blox data messages received as a string

To get this event you must turn the GPS on with Bangle.setGPSPower(1).

Note: This is only available in Bangle.js smartwatches

See Bangle.getHealthStatus() for more information. This is used for health tracking to allow Bangle.js to record historical exercise data.

Note: This is only available in Bangle.js smartwatches

Heat rate data, as an object. Contains:

{ "bpm": number,             // Beats per minute
  "confidence": number,      // 0-100 percentage confidence in the heart rate
  "raw": Uint8Array,         // raw samples from heart rate monitor
}

To get this event you must turn the heart rate monitor on with Bangle.setHRMPower(1).

Note: This is only available in Bangle.js smartwatches

Called when heart rate sensor data is available - see Bangle.setHRMPower(1).

hrm is of the form:

{ "raw": -1,       // raw value from sensor
  "filt": -1,      // bandpass-filtered raw value from sensor
  "bpm": 88.9,     // last BPM value measured
  "confidence": 0  // confidence in the BPM value
}

Note: This is only available in Bangle.js smartwatches

Read a register on the Heart rate monitor

Note: This is only available in Bangle.js smartwatches

Changes a pin state on the IO expander

Note: This is only available in Bangle.js 1 smartwatches

Also see the Bangle.backlight event

You can use Bangle.setLCDPowerBacklight to turn on the LCD backlight.

Note: This is only available in Bangle.js smartwatches

Note: This is only available in Bangle.js smartwatches

Is the compass powered?

Set power with Bangle.setCompassPower(...);

Note: This is only available in Bangle.js smartwatches

Is the GPS powered?

Set power with Bangle.setGPSPower(...);

Note: This is only available in Bangle.js smartwatches

Is the Heart rate monitor powered?

Set power with Bangle.setHRMPower(...);

Note: This is only available in Bangle.js smartwatches

Also see the Bangle.lcdPower event

You can use Bangle.setLCDPower to turn on the LCD (on Bangle.js 2 the LCD is normally on, and draws very little power so can be left on).

Note: This is only available in Bangle.js smartwatches

Also see the Bangle.lock event

Note: This is only available in Bangle.js smartwatches

Has the screen been turned on or off? Can be used to stop tasks that are no longer useful if nothing is displayed. Also see Bangle.isLCDOn()

Note: This is only available in Bangle.js smartwatches

Writes a command directly to the ST7735 LCD controller

Note: This is only available in Bangle.js smartwatches

This behaves the same as the global load() function, but if fast loading is possible (Bangle.setUI was called with a remove handler) then instead of a complete reload, the remove handler will be called and the new app will be loaded straight after with eval.

This should only be used if the app being loaded also uses widgets (eg it contains a Bangle.loadWidgets() call).

load() is slower, but safer. As such, care should be taken when using Bangle.load() with Bangle.setUI({..., remove:...}) as if your remove handler doesn't completely clean up after your app, memory leaks or other issues could occur - see Bangle.setUI for more information.

Note: This is only available in Bangle.js smartwatches

Load all widgets from flash Storage. Call this once at the beginning of your application if you want any on-screen widgets to be loaded.

They will be loaded into a global WIDGETS array, and can be rendered with Bangle.drawWidgets.

Note: This is only available in Bangle.js smartwatches

Has the screen been locked? Also see Bangle.isLocked()

Note: This is only available in Bangle.js smartwatches

Magnetometer/Compass data available with {x,y,z,dx,dy,dz,heading} object as a parameter

• x/y/z raw x,y,z magnetometer readings
• dx/dy/dz readings based on calibration since magnetometer turned on
• heading in degrees based on calibrated readings (will be NaN if magnetometer hasn't been rotated around 360 degrees).

Note: In 2v15 firmware and earlier the heading is inverted (360-heading). There's a fix in the bootloader which will apply a fix for those headings, but old apps may still expect an inverted value.

To get this event you must turn the compass on with Bangle.setCompassPower(1).

You can also retrieve the most recent reading with Bangle.getCompass().

Note: This is only available in Bangle.js smartwatches

Emitted at midnight (at the point the day health info is reset to 0).

Can be used for housekeeping tasks that don't want to be run during the day.

Note: This is only available in Bangle.js smartwatches

Turn Bangle.js off. It can only be woken by pressing BTN1.

Note: This is only available in Bangle.js smartwatches

When Bangle.setBarometerPower(true) is called, this event is fired containing barometer readings.

Same format as Bangle.getPressure()

Note: This is only available in Bangle.js smartwatches

Perform a Spherical Web Mercator projection of latitude and longitude into x and y coordinates, which are roughly equivalent to meters from {lat:0,lon:0}.

This is the formula used for most online mapping and is a good way to compare GPS coordinates to work out the distance between them.

Note: This is only available in Bangle.js smartwatches

Resets the compass minimum/maximum values. Can be used if the compass isn't providing a reliable heading any more.

Note: This is only available in Bangle.js smartwatches

This function can be used to turn Bangle.js's LCD backlight off or on.

This function resets the Bangle's 'activity timer' (like pressing a button or the screen would) so after a time period of inactivity set by Bangle.setOptions({backlightTimeout: X}); the backlight will turn off.

If you want to keep the backlight on permanently (until apps are changed) you can do:

Bangle.setOptions({backlightTimeout: 0}) // turn off the timeout
Bangle.setBacklight(1); // keep screen on

Of course, the backlight depends on Bangle.setLCDPower too, so any lcdPowerTimeout/setLCDTimeout will also turn the backlight off. The use case is when you require the backlight timeout to be shorter than the power timeout.

Note: This is only available in Bangle.js smartwatches

Set the power to the Compass

When on, data is output via the mag event on Bangle:

Bangle.setCompassPower(true, "myapp");
Bangle.on('mag',print);

When on, the compass draws roughly 2mA

Note: This is only available in Bangle.js smartwatches

Set the power to the GPS.

When on, data is output via the GPS event on Bangle:

Bangle.setGPSPower(true, "myapp");
Bangle.on('GPS',print);

When on, the GPS draws roughly 20mA

Note: This is only available in Bangle.js smartwatches

Set the power to the Heart rate monitor

When on, data is output via the HRM event on Bangle:

Bangle.setHRMPower(true, "myapp");
Bangle.on('HRM',print);

When on, the Heart rate monitor draws roughly 5mA

Note: This is only available in Bangle.js smartwatches

This function can be used to adjust the brightness of Bangle.js's display, and hence prolong its battery life.

Due to hardware design constraints on Bangle.js 1, software PWM has to be used which means that the display may flicker slightly when Bluetooth is active and the display is not at full power.

Power consumption

• 0 = 7mA
• 0.1 = 12mA
• 0.2 = 18mA
• 0.5 = 28mA
• 0.9 = 40mA (switching overhead)
• 1 = 40mA

In 2v21 and earlier, this function would erroneously turn the LCD backlight on. 2v22 and later fix this, and if you want the backlight on your should use Bangle.setLCDPowerBacklight()

Note: This is only available in Bangle.js smartwatches

This function can be used to change the way graphics is handled on Bangle.js.

Available options for Bangle.setLCDMode are:

• Bangle.setLCDMode() or Bangle.setLCDMode("direct") (the default) - The drawable area is 240x240 16 bit. Unbuffered, so draw calls take effect immediately. Terminal and vertical scrolling work (horizontal scrolling doesn't).
• Bangle.setLCDMode("doublebuffered") - The drawable area is 240x160 16 bit, terminal and scrolling will not work. g.flip() must be called for draw operations to take effect.
• Bangle.setLCDMode("120x120") - The drawable area is 120x120 8 bit, g.getPixel, terminal, and full scrolling work. Uses an offscreen buffer stored on Bangle.js, g.flip() must be called for draw operations to take effect.
• Bangle.setLCDMode("80x80") - The drawable area is 80x80 8 bit, g.getPixel, terminal, and full scrolling work. Uses an offscreen buffer stored on Bangle.js, g.flip() must be called for draw operations to take effect.

You can also call Bangle.setLCDMode() to return to normal, unbuffered "direct" mode.

Note: This is only available in Bangle.js smartwatches

This can be used to move the displayed memory area up or down temporarily. It's used for displaying notifications while keeping the main display contents intact.

Note: This is only available in Bangle.js smartwatches

This function can be used to turn Bangle.js's LCD off or on.

This function resets the Bangle's 'activity timer' (like pressing a button or the screen would) so after a time period of inactivity set by Bangle.setLCDTimeout the screen will turn off.

If you want to keep the screen on permanently (until apps are changed) you can do:

Bangle.setLCDTimeout(0); // turn off the timeout
Bangle.setLCDPower(1); // keep screen on

When on full, the LCD draws roughly 40mA. You can adjust When brightness using Bangle.setLCDBrightness.

Note: This is only available in Bangle.js smartwatches

This function can be used to turn Bangle.js's LCD power saving on or off.

With power saving off, the display will remain in the state you set it with Bangle.setLCDPower.

With power saving on, the display will turn on if a button is pressed, the watch is turned face up, or the screen is updated (see Bangle.setOptions for configuration). It'll turn off automatically after the given timeout.

Note: This function also sets the Backlight and Lock timeout (the time at which the touchscreen/buttons start being ignored). To set both separately, use Bangle.setOptions

Note: This is only available in Bangle.js smartwatches

This function can be used to lock or unlock Bangle.js (e.g. whether buttons and touchscreen work or not)

Note: This is only available in Bangle.js smartwatches

Set internal options used for gestures, etc...

• wakeOnBTN1 should the LCD turn on when BTN1 is pressed? default = true
• wakeOnBTN2 (Bangle.js 1) should the LCD turn on when BTN2 is pressed? default = true
• wakeOnBTN3 (Bangle.js 1) should the LCD turn on when BTN3 is pressed? default = true
• wakeOnFaceUp should the LCD turn on when the watch is turned face up? default = false
• wakeOnTouch should the LCD turn on when the touchscreen is pressed? On Bangle.js 1 this is a physical press on the touchscreen, on Bangle.js 2 we have to use the accelerometer as the touchscreen cannot be left powered without running the battery down. default = false
• wakeOnDoubleTap (2v20 onwards) should the LCD turn on when the watch is double-tapped on the screen? This uses the accelerometer, not the touchscreen itself. default = false
• wakeOnTwist should the LCD turn on when the watch is twisted? default = true
• twistThreshold How much acceleration to register a twist of the watch strap? Can be negative for opposite direction. default = 800
• twistMaxY Maximum acceleration in Y to trigger a twist (low Y means watch is facing the right way up). default = -800
• twistTimeout How little time (in ms) must a twist take from low->high acceleration? default = 1000
• gestureStartThresh how big a difference before we consider a gesture started? default = sqr(800)
• gestureEndThresh how small a difference before we consider a gesture ended? default = sqr(2000)
• gestureInactiveCount how many samples do we keep after a gesture has ended? default = 4
• gestureMinLength how many samples must a gesture have before we notify about it? default = 10
• powerSave after a minute of not being moved, Bangle.js will change the accelerometer poll interval down to 800ms (10x accelerometer samples). On movement it'll be raised to the default 80ms. If Bangle.setPollInterval is used this is disabled, and for it to work the poll interval must be either 80ms or 800ms. default = true. Setting powerSave:false will disable this automatic power saving, but will not change the poll interval from its current value. If you desire a specific interval (e.g. the default 80ms) you must set it manually with Bangle.setPollInterval(80) after setting powerSave:false.
• lowResistanceFix (Bangle.js 2, 2v22+) In the very rare case that your watch button gets damaged such that it has a low resistance and always stays on, putting the watch into a boot loop, setting this flag may improve matters (by forcing the input low before reading and disabling the hardware watch on BTN1).
• lockTimeout how many milliseconds before the screen locks
• lcdPowerTimeout how many milliseconds before the screen turns off
• backlightTimeout how many milliseconds before the screen's backlight turns off
• btnLoadTimeout how many milliseconds does the home button have to be pressed for before the clock is reloaded? 1500ms default, or 0 means never.
• manualWatchdog if set, this disables automatic kicking of the watchdog timer from the interrupt (when the button isn't held). You will then have to manually call E.kickWatchdog() from your code or the watch will reset after ~5 seconds.
• hrmPollInterval set the requested poll interval (in milliseconds) for the heart rate monitor. On Bangle.js 2 only 10,20,40,80,160,200 ms are supported, and polling rate may not be exact. The algorithm's filtering is tuned for 20-40ms poll intervals, so higher/lower intervals may effect the reliability of the BPM reading. You must call this before Bangle.setHRMPower - calling when the HRM is already on will not affect the poll rate.
• hrmSportMode - on the newest Bangle.js 2 builds with with the proprietary heart rate algorithm, this is the sport mode passed to the algorithm. See libs/misc/vc31_binary/algo.h for more info. -1 = auto, 0 = normal (default), 1 = running, 2 = ...
• hrmGreenAdjust - (Bangle.js 2, 2v19+) if false (default is true) the green LED intensity won't be adjusted to get the HRM sensor 'exposure' correct. This is reset when the HRM is initialised with Bangle.setHRMPower.
• hrmWearDetect - (Bangle.js 2, 2v19+) if false (default is true) HRM readings won't be turned off if the watch isn't on your arm (based on HRM proximity sensor). This is reset when the HRM is initialised with Bangle.setHRMPower.
• hrmPushEnv - (Bangle.js 2, 2v19+) if true (default is false) HRM environment readings will be produced as Bangle.on(HRM-env, ...) events. This is reset when the HRM is initialised with Bangle.setHRMPower.
• seaLevelPressure (Bangle.js 2) Normally 1013.25 millibars - this is used for calculating altitude with the pressure sensor
• lcdBufferPtr (Bangle.js 2 2v21+) Return a pointer to the first pixel of the 3 bit graphics buffer used by Bangle.js for the screen (stride = 178 bytes)
• lcdDoubleRefresh (Bangle.js 2 2v22+) If enabled, pulses EXTCOMIN twice per poll interval (avoids off-axis flicker)

Where accelerations are used they are in internal units, where 8192 = 1g

Note: This is only available in Bangle.js smartwatches

Set how often the watch should poll its sensors (accel/hr/mag) for new data and kick the Watchdog timer. It isn't recommended that you make this interval much larger than 1000ms, but values up to 4000ms are allowed.

Calling this will set Bangle.setOptions({powerSave: false}) - disabling the dynamic adjustment of poll interval to save battery power when Bangle.js is stationary.

Note: This is only available in Bangle.js smartwatches

Sets the current value of the step counter

Note: This is only available in Bangle.js smartwatches

This puts Bangle.js into the specified UI input mode, and calls the callback provided when there is user input.

Currently supported interface types are:

• 'updown' - UI input with upwards motion cb(-1), downwards motion cb(1), and select cb()
  • Bangle.js 1 uses BTN1/3 for up/down and BTN2 for select
  • Bangle.js 2 uses touchscreen swipe up/down and tap
• 'leftright' - UI input with left motion cb(-1), right motion cb(1), and select cb()
  • Bangle.js 1 uses BTN1/3 for left/right and BTN2 for select
  • Bangle.js 2 uses touchscreen swipe left/right and tap/BTN1 for select
• 'clock' - called for clocks. Sets Bangle.CLOCK=1 and allows a button to start the launcher
  • Bangle.js 1 BTN2 starts the launcher
  • Bangle.js 2 BTN1 starts the launcher
• 'clockupdown' - called for clocks. Sets Bangle.CLOCK=1, allows a button to start the launcher, but also provides up/down functionality
  • Bangle.js 1 BTN2 starts the launcher, BTN1/BTN3 call cb(-1) and cb(1)
  • Bangle.js 2 BTN1 starts the launcher, touchscreen tap in top/bottom right hand side calls cb(-1) and cb(1)
• {mode:"custom", ...} allows you to specify custom handlers for different interactions. See below.
• undefined removes all user interaction code

While you could use setWatch/etc manually, the benefit here is that you don't end up with multiple setWatch instances, and the actual input method (touch, or buttons) is implemented dependent on the watch (Bangle.js 1 or 2)

Bangle.setUI("updown", function (dir) {
  // dir is +/- 1 for swipes up/down
  // dir is 0 when button pressed
});

The first argument can also be an object, in which case more options can be specified with mode:"custom":

Bangle.setUI({
  mode : "custom",
  back : function() {}, // optional - add a 'back' icon in top-left widget area and call this function when it is pressed , also call it when the hardware button is clicked (does not override btn if defined)
  remove : function() {}, // optional - add a handler for when the UI should be removed (eg stop any intervals/timers here)
  redraw : function() {}, // optional - add a handler to redraw the UI. Not needed but it can allow widgets/etc to provide other functionality that requires the screen to be redrawn
  touch : function(n,e) {}, // optional - (mode:custom only) handler for 'touch' events
  swipe : function(dir) {}, // optional - (mode:custom only) handler for 'swipe' events
  drag : function(e) {}, // optional - (mode:custom only) handler for 'drag' events (Bangle.js 2 only)
  btn : function(n) {}, // optional - (mode:custom only) handler for 'button' events (n==1 on Bangle.js 2, n==1/2/3 depending on button for Bangle.js 1)
  clock : 0 // optional - if set the behavior of 'clock' mode is added (does not override btn if defined)
});

If remove is specified, Bangle.showLauncher, Bangle.showClock, Bangle.load and some apps may choose to just call the remove function and then load a new app without resetting Bangle.js. As a result, if you specify 'remove' you should make sure you test that after calling Bangle.setUI() without arguments your app is completely unloaded, otherwise you may end up with memory leaks or other issues when switching apps. Please see the Bangle.js Fast Load Tutorial for more details on this.

Note: You can override this function in boot code to change the interaction mode with the watch. For instance you could make all clocks start the launcher with a swipe by using:

(function() {
  var sui = Bangle.setUI;
  Bangle.setUI = function(mode, cb) {
    var m = ("object"==typeof mode) ? mode.mode : mode;
    if (m!="clock") return sui(mode,cb);
    sui(); // clear
    Bangle.CLOCK=1;
    Bangle.swipeHandler = Bangle.showLauncher;
    Bangle.on("swipe", Bangle.swipeHandler);
  };
})();

Note: This is only available in Bangle.js smartwatches

Load the Bangle.js clock - this has the same effect as calling Bangle.load().

Note: This is only available in Bangle.js smartwatches

Load the Bangle.js app launcher, which will allow the user to select an application to launch.

Note: This is only available in Bangle.js smartwatches

Note: This is only available in Bangle.js smartwatches

Note: This is only available in Bangle.js smartwatches with Bangle.js 1 smartwatches

Turn Bangle.js (mostly) off, but keep the CPU in sleep mode until BTN1 is pressed to preserve the RTC (current time).

Note: This is only available in Bangle.js smartwatches

Called whenever a step is detected by Bangle.js's pedometer.

Note: This is only available in Bangle.js smartwatches

Emitted when a swipe on the touchscreen is detected (a movement from left->right, right->left, down->up or up->down)

Bangle.js 1 is only capable of detecting left/right swipes as it only contains a 2 zone touchscreen.

Note: This is only available in Bangle.js smartwatches

If the watch is tapped, this event contains information on the way it was tapped.

dir reports the side of the watch that was tapped (not the direction it was tapped in).

{
  dir : "left/right/top/bottom/front/back",
  double : true/false // was this a double-tap?
  x : -2 .. 2, // the axis of the tap
  y : -2 .. 2, // the axis of the tap
  z : -2 .. 2 // the axis of the tap

Note: This is only available in Bangle.js smartwatches

Emitted when the touchscreen is pressed

Note: This is only available in Bangle.js smartwatches

Writes a register on the touch controller

Note: This is only available in Bangle.js smartwatches

This event happens when the watch has been twisted around it's axis - for instance as if it was rotated so someone could look at the time.

To tweak when this happens, see the twist* options in Bangle.setOptions()

Note: This is only available in Bangle.js smartwatches

A Web Bluetooth-style device - you can request one using NRF.requestDevice(options)

For example:

var gatt;
NRF.requestDevice({ filters: [{ name: 'Puck.js abcd' }] }).then(function(device) {
  console.log("found device");
  return device.gatt.connect();
}).then(function(g) {
  gatt = g;
  console.log("connected");
  return gatt.startBonding();
}).then(function() {
  console.log("bonded", gatt.getSecurityStatus());
  gatt.disconnect();
}).catch(function(e) {
  console.log("ERROR",e);
});

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

Called when the device gets disconnected.

To connect and then print Disconnected when the device is disconnected, just do the following:

var gatt;
NRF.connect("aa:bb:cc:dd:ee:ff").then(function(gatt) {
  gatt.device.on('gattserverdisconnected', function(reason) {
    console.log("Disconnected ",reason);
  });
});

Or:

var gatt;
NRF.requestDevice(...).then(function(device) {
  device.on('gattserverdisconnected', function(reason) {
    console.log("Disconnected ",reason);
  });
});

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q)

Called when the device pairs and sends a passkey that Espruino should display.

For this to be used, you'll have to specify that there's a display using NRF.setSecurity

This is not part of the Web Bluetooth Specification. It has been added specifically for Espruino.

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q)

Called when the device pairs, displays a passkey, and wants Espruino to tell it what the passkey was.

Respond with BluetoothDevice.sendPasskey("123456") with a 6 character string containing only 0..9.

For this to be used, you'll have to specify that there's a keyboard using NRF.setSecurity

This is not part of the Web Bluetooth Specification. It has been added specifically for Espruino.

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q)

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q)

To be used as a response when the event BluetoothDevice.sendPasskey has been received.

This is not part of the Web Bluetooth Specification. It has been added specifically for Espruino.

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q)

Web Bluetooth-style GATT characteristic - get this using BluetoothRemoteGATTService.getCharacteristic(s)

https://webbluetoothcg.github.io/web-bluetooth/#bluetoothremotegattcharacteristic

Called when a characteristic's value changes, after BluetoothRemoteGATTCharacteristic.startNotifications has been called.

  ...
  return service.getCharacteristic("characteristic_uuid");
}).then(function(c) {
  c.on('characteristicvaluechanged', function(event) {
    console.log("-> "+event.target.value);
  });
  return c.startNotifications();
}).then(...

The first argument is of the form

{target :
BluetoothRemoteGATTCharacteristic}

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

Read a characteristic's value, return a promise containing a DataView

var device;
NRF.connect(device_address).then(function(d) {
  device = d;
  return d.getPrimaryService("service_uuid");
}).then(function(s) {
  console.log("Service ",s);
  return s.getCharacteristic("characteristic_uuid");
}).then(function(c) {
  return c.readValue();
}).then(function(d) {
  console.log("Got:", JSON.stringify(d.buffer));
  device.disconnect();
}).catch(function() {
  console.log("Something's broken.");
});

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q)

Starts notifications - whenever this characteristic's value changes, a characteristicvaluechanged event is fired and characteristic.value will then contain the new value as a DataView.

var device;
NRF.connect(device_address).then(function(d) {
  device = d;
  return d.getPrimaryService("service_uuid");
}).then(function(s) {
  console.log("Service ",s);
  return s.getCharacteristic("characteristic_uuid");
}).then(function(c) {
  c.on('characteristicvaluechanged', function(event) {
    console.log("-> ",event.target.value); // this is a DataView
  });
  return c.startNotifications();
}).then(function(d) {
  console.log("Waiting for notifications");
}).catch(function() {
  console.log("Something's broken.");
});

For example, to listen to the output of another Puck.js's Nordic Serial port service, you can use:

var gatt;
NRF.connect("pu:ck:js:ad:dr:es random").then(function(g) {
  gatt = g;
  return gatt.getPrimaryService("6e400001-b5a3-f393-e0a9-e50e24dcca9e");
}).then(function(service) {
  return service.getCharacteristic("6e400003-b5a3-f393-e0a9-e50e24dcca9e");
}).then(function(characteristic) {
  characteristic.on('characteristicvaluechanged', function(event) {
    console.log("RX: "+JSON.stringify(event.target.value.buffer));
  });
  return characteristic.startNotifications();
}).then(function() {
  console.log("Done!");
});

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

Stop notifications (that were requested with BluetoothRemoteGATTCharacteristic.startNotifications)

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q)

Write a characteristic's value

var device;
NRF.connect(device_address).then(function(d) {
  device = d;
  return d.getPrimaryService("service_uuid");
}).then(function(s) {
  console.log("Service ",s);
  return s.getCharacteristic("characteristic_uuid");
}).then(function(c) {
  return c.writeValue("Hello");
}).then(function(d) {
  device.disconnect();
}).catch(function() {
  console.log("Something's broken.");
});

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

Web Bluetooth-style GATT server - get this using NRF.connect(address) or NRF.requestDevice(options) and response.gatt.connect

https://webbluetoothcg.github.io/web-bluetooth/#bluetoothremotegattserver

Connect to a BLE device - returns a promise, the argument of which is the BluetoothRemoteGATTServer connection.

See NRF.requestDevice for usage examples.

options is an optional object containing:

{
   minInterval // min connection interval in milliseconds, 7.5 ms to 4 s
   maxInterval // max connection interval in milliseconds, 7.5 ms to 4 s
}

By default the interval is 20-200ms (or 500-1000ms if NRF.setLowPowerConnection(true) was called. During connection Espruino negotiates with the other device to find a common interval that can be used.

For instance calling:

NRF.requestDevice({ filters: [{ namePrefix: 'Pixl.js' }] }).then(function(device) {
  return device.gatt.connect({minInterval:7.5, maxInterval:7.5});
}).then(function(g) {

will force the connection to use the fastest connection interval possible (as long as the device at the other end supports it).

Note: The Web Bluetooth spec states that if a device hasn't advertised its name, when connected to a device the central (in this case Espruino) should automatically retrieve the name from the corresponding characteristic (0x2a00 on service 0x1800). Espruino does not automatically do this.

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

Disconnect from a previously connected BLE device connected with BluetoothRemoteGATTServer.connect - this does not disconnect from something that has connected to the Espruino.

Note: While .disconnect is standard Web Bluetooth, in the spec it returns undefined not a Promise for implementation reasons. In Espruino we return a Promise to make it easier to detect when Espruino is free to connect to something else.

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

See NRF.connect for usage examples.

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

Return an object with information about the security state of the current connection:

{
  connected       // The connection is active (not disconnected).
  encrypted       // Communication on this link is encrypted.
  mitm_protected  // The encrypted communication is also protected against man-in-the-middle attacks.
  bonded          // The peer is bonded with us
}

See BluetoothRemoteGATTServer.startBonding for information about negotiating a secure connection.

This is not part of the Web Bluetooth Specification. It has been added specifically for Puck.js.

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q)

Start/stop listening for RSSI values on the active GATT connection

// Start listening for RSSI value updates
gattServer.setRSSIHandler(function(rssi) {
  console.log(rssi); // prints -85 (or similar)
});
// Stop listening
gattServer.setRSSIHandler();

RSSI is the 'Received Signal Strength Indication' in dBm

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

Start negotiating bonding (secure communications) with the connected device, and return a Promise that is completed on success or failure.

var gatt;
NRF.requestDevice({ filters: [{ name: 'Puck.js abcd' }] }).then(function(device) {
  console.log("found device");
  return device.gatt.connect();
}).then(function(g) {
  gatt = g;
  console.log("connected");
  return gatt.startBonding();
}).then(function() {
  console.log("bonded", gatt.getSecurityStatus());
  gatt.disconnect();
}).catch(function(e) {
  console.log("ERROR",e);
});

This is not part of the Web Bluetooth Specification. It has been added specifically for Espruino.

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q)

Web Bluetooth-style GATT service - get this using BluetoothRemoteGATTServer.getPrimaryService(s)

https://webbluetoothcg.github.io/web-bluetooth/#bluetoothremotegattservice

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q)

See NRF.connect for usage examples.

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

Note: This is only available in NRF52 devices (like Puck.js, Pixl.js, Jolt.js, Bangle.js and MDBT42Q) and ESP32 boards

Creates a boolean

An Object that contains functions for writing to the interactive console

Implemented in Espruino as an alias of console.log

Implemented in Espruino as an alias of console.log

Implemented in Espruino as an alias of console.log

Print the supplied string(s) to the console

Note:* If you're connected to a computer (not a wall adaptor) via USB but *you are not running a terminal app then when you print data Espruino may pause execution and wait until the computer requests the data it is trying to print.

Implemented in Espruino as an alias of console.log

This class helps

Create a DataView object that can be used to access the data in an ArrayBuffer.

var b = new ArrayBuffer(8)
var v = new DataView(b)
v.setUint16(0,"0x1234")
v.setUint8(3,"0x56")
console.log("0x"+v.getUint32(0).toString(16))
// prints 0x12340056

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

The built-in class for handling Dates.

Note: By default the time zone is GMT+0, however you can change the timezone using the E.setTimeZone(...) function.

For example E.setTimeZone(1) will be GMT+0100

However if you have daylight savings time set with E.setDST(...) then the timezone set by E.setTimeZone(...) will be ignored.

Creates a date object

Day of the month 1..31

Day of the week (0=sunday, 1=monday, etc)

The year, e.g. 2014

0..23

This returns a boolean indicating whether daylight savings time is in effect.

Note: This is not available in devices with low flash memory

0..999

0..59

Month of the year 0..11

0..59

Return the number of milliseconds since 1970

This returns the time-zone offset from UTC, in minutes.

Note: This is not available in devices with low flash memory

Get the number of milliseconds elapsed since 1970 (or on embedded platforms, since startup).

Note: Desktop JS engines return an integer value for Date.now(), however Espruino returns a floating point value, accurate to fractions of a millisecond.

Parse a date string and return milliseconds since 1970. Data can be either '2011-10-20T14:48:00', '2011-10-20' or 'Mon, 25 Dec 1995 13:30:00 +0430'

Day of the month 1..31

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

0..23

Note: This is not available in devices with low flash memory

Note: This is not available in devices with low flash memory

0..59

Note: This is not available in devices with low flash memory

Month of the year 0..11

Note: This is not available in devices with low flash memory

0..59

Note: This is not available in devices with low flash memory

Set the time/date of this Date class

Converts to a ISO 8601 String, e.g: 2014-06-20T14:52:20.123Z

Note: This always assumes a timezone of GMT

Calls Date.toISOString to output this date to JSON

Converts to a ISO 8601 String (with timezone information), e.g: 2014-06-20T14:52:20.123-0500

Note: This is not available in devices with low flash memory

Converts to a String, e.g: Fri Jun 20 2014 14:52:20 GMT+0000

Note: This uses whatever timezone was set with E.setTimeZone() or E.setDST()

Converts to a String, e.g: Fri, 20 Jun 2014 14:52:20 GMT

Note: This always assumes a timezone of GMT

Note: This is not available in devices with low flash memory

Return the number of milliseconds since 1970

This is the built-in JavaScript class for Espruino utility functions.

Called when a media event arrives on an Apple iOS device Bangle.js is connected to

{
id : "artist"/"album"/"title"/"duration",
value : "Some text",
truncated : bool // the 'value' was too big to be sent completely
}

Note: This is only available in Bangle.js smartwatches

Called when a notification arrives on an Apple iOS device Bangle.js is connected to

{
event:"add",
uid:42,
category:4,
categoryCnt:42,
silent:true,
important:false,
preExisting:true,
positive:false,
negative:true
}

You can then get more information with NRF.ancsGetNotificationInfo, for instance:

E.on('ANCS', event => {
  NRF.ancsGetNotificationInfo( event.uid ).then(a=>print("Notify",E.toJS(a)));
});

Note: This is only available in Bangle.js smartwatches

Provide assembly to Espruino.

This function is not part of Espruino. Instead, it is detected by the Espruino IDE (or command-line tools) at upload time and is replaced with machine code and an E.nativeCall call.

See the documentation on the Assembler for more information.

Note: This is not available in devices with low flash memory

By default, strings in Espruino are standard 8 bit binary strings unless they contain Unicode chars or a \u#### escape code that doesn't map to the range 0..255.

However calling E.asUTF8 will convert one of those strings to UTF8.

var s = String.fromCharCode(0xF0,0x9F,0x8D,0x94);
var u = E.asUTF8(s);
s.length // 4
s[0] // "\xF0"
u.length // 1
u[0] // hamburger emoji

NOTE: UTF8 is currently only available on Bangle.js devices

Note: This is not available in devices with low flash memory

Clip a number to be between min and max (inclusive)

Note: This is not available in devices with low flash memory

Called when a bit rises or falls above a set level. See E.setComparator for setup.

Note: This is only available in NRF52 with not devices with low flash memory

Provides the ability to write C code inside your JavaScript file.

This function is not part of Espruino. Instead, it is detected by the Espruino IDE (or command-line tools) at upload time, is sent to our web service to be compiled, and is replaced with machine code and an E.nativeCall call.

See the documentation on Inline C for more information and examples.

Note: This is not available in devices with low flash memory

Convolve arr1 with arr2. This is equivalent to

v=0;for (i in arr1) v+=arr1[i] *
arr2[(i+offset) % arr2.length]

Note: This is not available in devices with low flash memory

Perform a standard 32 bit CRC (Cyclic redundancy check) on the supplied data (one byte at a time) and return the result as an unsigned integer.

Note: This is not available in devices with low flash memory

Decode a UTF8 string.

• Any decoded character less than 256 gets passed straight through
• Otherwise if lookup is an array and an item with that char code exists in lookup then that is used
• Otherwise if lookup is an object and an item with that char code (as lowercase hex) exists in lookup then that is used
• Otherwise replaceFn(charCode) is called and the result used if replaceFn is a function
• If replaceFn is a string, that is used
• Or finally if nothing else matches, the character is ignored

For instance:

let unicodeRemap = {
  0x20ac:"\u0080", // Euro symbol
  0x2026:"\u0085", // Ellipsis
};
E.decodeUTF8("UTF-8 Euro: \u00e2\u0082\u00ac", unicodeRemap, '[?]') == "UTF-8 Euro: \u0080"

Note: This is not available in devices with low flash memory

BETA: defragment memory!

Note: This is not available in devices with low flash memory

Show fragmentation.

• is free space
• # is a normal variable
• L is a locked variable (address used, cannot be moved)
• = represents data in a Flat String (must be contiguous)

Note: This is not available in devices with low flash memory

Dump any locked variables that aren't referenced from global - for debugging memory leaks only.

Note: This is not available in release builds

Dump any locked variables that aren't referenced from global - for debugging memory leaks only.

Note: This does a linear scan over memory, finding variables that are currently locked. In some cases it may show variables like Unknown 66 which happen when part of a string has ended up placed in memory ahead of the String that it's part of. See https://github.com/espruino/Espruino/issues/2345

Note: This is not available in release builds

Get the current interpreter state in a text form such that it can be copied to a new device

Note: This is not available in devices with low flash memory

Output the current list of Utility Timer Tasks - for debugging only

Note: This is not available in devices with low flash memory

Dumps a comma-separated list of all allocated variables along with the variables they link to. Can be used to visualise where memory is used.

Note: This is not available in devices with low flash memory

Enable the watchdog timer. This will reset Espruino if it isn't able to return to the idle loop within the timeout.

If isAuto is false, you must call E.kickWatchdog() yourself every so often or the chip will reset.

E.enableWatchdog(0.5); // automatic mode
while(1); // Espruino will reboot because it has not been idle for 0.5 sec

E.enableWatchdog(1, false);
setInterval(function() {
  if (everything_ok)
    E.kickWatchdog();
}, 500);
// Espruino will now reset if everything_ok is false,
// or if the interval fails to be called

NOTE: This is only implemented on STM32, nRF5x and ESP32 devices (all official Espruino boards).

NOTE:* On STM32 (Pico, WiFi, Original) with setDeepSleep(1) you need to explicitly wake Espruino up with an interval of less than the watchdog timeout or the watchdog will fire and the board will reboot. You can do this with setInterval("", time_in_milliseconds). *NOTE: On ESP32, the timeout will be rounded to the nearest second.

Note: This is not available in devices with low flash memory

This event is called when an error is created by Espruino itself (rather than JS code) which changes the state of the error flags reported by E.getErrorFlags()

This could be low memory, full buffers, UART overflow, etc. E.getErrorFlags() has a full description of each type of error.

This event will only be emitted when error flag is set. If the error flag was already set nothing will be emitted. To clear error flags so that you do get a callback each time a flag is set, call E.getErrorFlags().

Performs a Fast Fourier Transform (FFT) in 32 bit floats on the supplied data and writes it back into the original arrays. Note that if only one array is supplied, the data written back is the modulus of the complex result sqrt(r*r+i*i).

In order to perform the FFT, there has to be enough room on the stack to allocate two arrays of 32 bit floating point numbers - this will limit the maximum size of FFT possible to around 1024 items on most platforms.

Note: on the Original Espruino board, FFTs are performed in 64bit arithmetic as there isn't space to include the 32 bit maths routines (2x more RAM is required).

Note: This is not available in devices with low flash memory

Given a UTF8 String (see E.asUTF8) this returns the underlying representation of that String.

E.fromUTF8("\u03C0") == "\xCF\x80"

NOTE: UTF8 is currently only available on Bangle.js devices

Note: This is not available in devices with low flash memory

Return the address in memory of the given variable. This can then be used with peek and poke functions. However, changing data in JS variables directly (flatAddress=false) will most likely result in a crash.

This functions exists to allow embedded targets to set up peripherals such as DMA so that they write directly to JS variables.

See http://www.espruino.com/Internals for more information

Note: This is not available in devices with low flash memory

Check the internal voltage reference. To work out an actual voltage of an input pin, you can use analogRead(pin)*E.getAnalogVRef()

Note: This value is calculated by reading the voltage on an internal voltage reference with the ADC. It will be slightly noisy, so if you need this for accurate measurements we'd recommend that you call this function several times and average the results.

While this is implemented on Espruino boards, it may not be implemented on other devices. If so it'll return NaN.

Note: This is not available in devices with low flash memory

In devices that come with batteries, this function returns the battery charge percentage as an integer between 0 and 100.

Note: this is an estimation only, based on battery voltage. The temperature of the battery (as well as the load being drawn from it at the time E.getBattery is called) will affect the readings.

Note: This is only available in Puck.js devices and Pixl.js boards and Bangle.js smartwatches

On boards other than STM32 this currently just returns undefined

STM32

See E.setClock for more information.

Returns:

{
  sysclk, hclk, pclk1, pclk2,  // various clocks in Hz
  M, N, P, Q, PCLK1, PCLK2     // STM32F4: currently set divisors
  RTCCLKSource : "LSI/LSE/HSE_Div#" // STM32F4 source for RTC clock
}

Note: This is not available in devices with low flash memory

Returns the current console device - see E.setConsole for more information.

Get and reset the error flags. Returns an array that can contain:

'FIFO_FULL': The receive FIFO filled up and data was lost. This could be state transitions for setWatch, or received characters.

'BUFFER_FULL': A buffer for a stream filled up and characters were lost. This can happen to any stream - Serial,HTTP,etc.

'CALLBACK': A callback (setWatch, setInterval, on('data',...)) caused an error and so was removed.

'LOW_MEMORY': Memory is running low - Espruino had to run a garbage collection pass or remove some of the command history

'MEMORY': Espruino ran out of memory and was unable to allocate some data that it needed.

'UART_OVERFLOW' : A UART received data but it was not read in time and was lost

Note: This is not available in devices with low flash memory

Get Espruino's interpreter flags that control the way it handles your JavaScript code.

• deepSleep - Allow deep sleep modes (also set by setDeepSleep)
• pretokenise - When adding functions, pre-minify them and tokenise reserved words
• unsafeFlash - Some platforms stop writes/erases to interpreter memory to stop you bricking the device accidentally - this removes that protection
• unsyncFiles - When writing files, don't flush all data to the SD card after each command (the default is to flush). This is much faster, but can cause filesystem damage if power is lost without the filesystem unmounted.

This function returns an object detailing the current estimated power usage of the Espruino device in microamps (uA). It is not intended to be a replacement for measuring actual power consumption, but can be useful for finding obvious power draws.

Where an Espruino device has outputs that are connected to other things, those are not included in the power usage figures.

Results look like:

{
  device: {
    CPU : 2000, // microcontroller
    LCD : 100, // LCD
    // ...
  },
  total : 5500 // estimated usage in microamps
}

Note: Currently only nRF52-based devices have variable CPU power usage figures. These are based on the time passed for each SysTick event, so under heavy usage the figure will update within 0.3s, but under low CPU usage it could take minutes for the CPU usage figure to update.

Note: On Jolt.js we take account of internal resistance on H0/H2/H4/H6 where we can measure voltage. H1/H3/H5/H7 cannot be measured.

Note: This is not available in devices with low flash memory

Return the number of variable blocks used by the supplied variable. This is useful if you're running out of memory and you want to be able to see what is taking up most of the available space.

If depth>0 and the variable can be recursed into, an array listing all property names (including internal Espruino names) and their sizes is returned. If depth>1 there is also a more field that inspects the objects' children's children.

For instance E.getSizeOf(function(a,b) { }) returns 5.

But E.getSizeOf(function(a,b) { }, 1) returns:

 [
  {
    "name": "a",
    "size": 1 },
  {
    "name": "b",
    "size": 1 },
  {
    "name": "\xFFcod",
    "size": 2 }
 ]

In this case setting depth to 2 will make no difference as there are no more children to traverse.

See http://www.espruino.com/Internals for more information

Note: This is not available in devices with low flash memory

Use the microcontroller's internal thermistor to work out the temperature.

On Puck.js v2.0 this will use the on-board PCT2075TP temperature sensor, but on other devices it may not be desperately well calibrated.

While this is implemented on Espruino boards, it may not be implemented on other devices. If so it'll return NaN.

Note:* This is not entirely accurate and varies by a few degrees from chip to chip. It measures the *die temperature, so when connected to USB it could be reading 10 over degrees C above ambient temperature. When running from battery with setDeepSleep(true) it is much more accurate though.

Convert hue, saturation and brightness to red, green and blue (packed into an integer if asArray==false or an array if asArray==true).

This replaces Graphics.setColorHSB and Graphics.setBgColorHSB. On devices with 24 bit colour it can be used as: Graphics.setColor(E.HSBtoRGB(h, s, b)), or on devices with 26 bit colour use Graphics.setColor(E.HSBtoRGB(h, s, b, 16))

You can quickly set RGB items in an Array or Typed Array using array.set(E.HSBtoRGB(h, s, b, true), offset), which can be useful with arrays used with require("neopixel").write.

Note: This is not available in devices with low flash memory

Unlike 'Math.random()' which uses a pseudo-random number generator, this method reads from the internal voltage reference several times, XOR-ing and rotating to try and make a relatively random value from the noise in the signal.

Note: This is not available in devices with low flash memory

This event is called right after the board starts up, and has a similar effect to creating a function called onInit.

For example to write "Hello World" every time Espruino starts, use:

E.on('init', function() {
  console.log("Hello World!");
});

Note:* that subsequent calls to E.on('init', will *add a new handler, rather than replacing the last one. This allows you to write modular code - something that was not possible with onInit.

By default, strings in Espruino are standard 8 bit binary strings unless they contain Unicode chars or a \u#### escape code that doesn't map to the range 0..255.

This checks if a String is being treated by Espruino as a UTF8 String

See E.asUTF8 to convert to a UTF8 String

NOTE: UTF8 is currently only available on Bangle.js devices

Note: This is not available in devices with low flash memory

Kicks a Watchdog timer set up with E.enableWatchdog(..., false). See E.enableWatchdog for more information.

NOTE: This is only implemented on STM32 and nRF5x devices (all official Espruino boards).

Note: This is not available in devices with low flash memory

This event is called just before the device shuts down for commands such as reset(), load(), save(), E.reboot() or Bangle.off()

For example to write "Bye!" just before shutting down use:

E.on('kill', function() {
  console.log("Bye!");
});

NOTE: This event is not called when the device is 'hard reset' - for example by removing power, hitting an actual reset button, or via a Watchdog timer reset.

If a password has been set with E.setPassword(), this will lock the console so the password needs to be entered to unlock it.

Note: This is not available in devices with low flash memory

Search in an Object, Array, or Function

Take each element of the from array, look it up in map (or call map(value,index) if it is a function), and write it into the corresponding element in the to array.

You can use an array to map:

var a = new Uint8Array([1,2,3,1,2,3]);
var lut = new Uint8Array([128,129,130,131]);
E.mapInPlace(a, a, lut);
// a = [129, 130, 131, 129, 130, 131]

Or undefined to pass straight through, or a function to do a normal 'mapping':

var a = new Uint8Array([0x12,0x34,0x56,0x78]);
var b = new Uint8Array(8);
E.mapInPlace(a, b, undefined); // straight through
// b = [0x12,0x34,0x56,0x78,0,0,0,0]
E.mapInPlace(a, b, (value,index)=>index); // write the index in the first 4 (because a.length==4)
// b = [0,1,2,3,4,0,0,0]
E.mapInPlace(a, b, undefined, 4); // 4 bits from 8 bit input -> 2x as many outputs, msb-first
// b = [1, 2, 3, 4, 5, 6, 7, 8]
 E.mapInPlace(a, b, undefined, -4); // 4 bits from 8 bit input -> 2x as many outputs, lsb-first
// b = [2, 1, 4, 3, 6, 5, 8, 7]
E.mapInPlace(a, b, a=>a+2, 4);
// b = [3, 4, 5, 6, 7, 8, 9, 10]
var b = new Uint16Array(4);
E.mapInPlace(a, b, undefined, 12); // 12 bits from 8 bit input, msb-first
// b = [0x123, 0x456, 0x780, 0]
E.mapInPlace(a, b, undefined, -12); // 12 bits from 8 bit input, lsb-first
// b = [0x412, 0x563, 0x078, 0]

Note: This is not available in devices with low flash memory

This creates and returns a special type of string, which references a specific address in memory. It can be used in order to use sections of Flash memory directly in Espruino (for example Storage uses it to allow files to be read directly from Flash).

Note: As of 2v21, Calling E.memoryArea with an address of 0 will return undefined

Create an object where every field accesses a specific 32 bit address in the microcontroller's memory. This is perfect for accessing on-chip peripherals.

// for NRF52 based chips
var GPIO = E.memoryMap(0x50000000,{OUT:0x504, OUTSET:0x508, OUTCLR:0x50C, IN:0x510, DIR:0x514, DIRSET:0x518, DIRCLR:0x51C});
GPIO.DIRSET = 1; // set GPIO0 to output
GPIO.OUT ^= 1; // toggle the output state of GPIO0

Note: This is not available in devices with low flash memory

ADVANCED: It's very easy to crash Espruino using this function if you get the code/arguments you supply wrong!

Create a native function that executes the code at the given address, e.g. E.nativeCall(0x08012345,'double (double,double)')(1.1, 2.2)

If you're executing a thumb function, you'll almost certainly need to set the bottom bit of the address to 1.

Note it's not guaranteed that the call signature you provide can be used - there are limits on the number of arguments allowed (5).

When supplying data, if it is a 'flat string' then it will be used directly, otherwise it'll be converted to a flat string and used.

The argument types in sig are:

• void - returns nothing
• bool - boolean value
• int - 32 bit integer
• double - 64 bit floating point
• float - 32 bit floating point (2v21 and later)
• Pin - Espruino 'pin' value (8 bit integer)
• JsVar - Pointer to an Espruino JsVar structure

Note: This is not available in devices with low flash memory

Pipe one stream to another.

This can be given any object with a read method as a source, and any object with a .write(data) method as a destination.