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

On Puck.js V2 (not v1.0) this is the pin that controls the FET, for high-powered outputs.

Note: This is only available in Puck.js devices

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

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.

The first I2C port

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

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

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.

Save the state of the interpreter into flash (including the results of calling setWatch, setInterval, pinMode, and any listeners). The state will then be loaded automatically every time Espruino powers on or is hard-reset. To see what will get saved you can call dump().

Note: If you set up intervals/etc in onInit() and you have already called onInit before running save(), when Espruino resumes there will be two copies of your intervals - the ones from before the save, and the ones from after - which may cause you problems.

For more information about this and other options for saving, please see the Saving code on Espruino page.

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

When Espruino powers on, it will resume from where it was when you typed save(). If you want code to be executed right after loading (for instance to initialise devices connected to Espruino), add a function called onInit, or add a init event handler to E with

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

In order to stop the program saved with this command being loaded automatically, check out the Troubleshooting guide

Note: This is not available in Bangle.js smartwatches

The first Serial (USART) port

Note: This is only available in devices with more than 1 ESPR_USART 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.

The first SPI port

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

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

Class containing AES encryption/decryption

Note: This library is currently only included in builds for boards where there is space. For other boards there is crypto.js which implements SHA1 in JS.

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

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'

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: 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: 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

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]), ...]

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: 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

Do an in-place quicksort of the array

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

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

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);
});

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)

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 devices with Bluetooth LE capability

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

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 devices with Bluetooth LE capability

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

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

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

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

Cryptographic functions

Note: This library is currently only included in builds for boards where there is space. For other boards there is crypto.js which implements SHA1 in JS.

Class containing AES encryption/decryption

Note: This is only available in devices that support AES (Espruino Pico, Espruino WiFi or Linux)

Performs a SHA1 hash and returns the result as a 20 byte ArrayBuffer.

Note: On some boards (currently only Espruino Original) there isn't space for a fully unrolled SHA1 implementation so a slower all-JS implementation is used instead.

Note: This is only available in devices that support Crypto Functionality (Espruino Pico, Original, Espruino WiFi, Espruino BLE devices, Linux or ESP8266)

Performs a SHA224 hash and returns the result as a 28 byte ArrayBuffer

Note: This is only available in devices that support SHA256 (Espruino Pico, Espruino WiFi, Espruino BLE devices or Linux)

Performs a SHA256 hash and returns the result as a 32 byte ArrayBuffer

Note: This is only available in devices that support SHA256 (Espruino Pico, Espruino WiFi, Espruino BLE devices or Linux)

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

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

0..23

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

Return the number of milliseconds since 1970

This library allows you to create UDP/DATAGRAM servers and clients

In order to use this, you will need an extra module to get network connectivity.

This is designed to be a cut-down version of the node.js library. Please see the Internet page for more information on how to use it.

Create a UDP socket

An actual socket connection - allowing transmit/receive of TCP data

Close the socket

Called when the connection closes.

The 'message' event is called when a datagram message is received. If a handler is defined with X.on('message', function(msg) { ... }) then it will be called`

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

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

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

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.

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.

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.

Data will be piped from source to destination in the idle loop until source.read(...) returns undefined.

For instance:

``` // Print a really big string to the console, 1 character at a time and write 'Finished!' at the end E.pipe("This is a really big String", {write: print}, {chunkSize:1, complete:()=>print("Finished!")});

// Pipe the numbers 1 to 100 to a StorageFile in Storage E.pipe({ n:0, read : function() { if (this.n<100) return (this.n++)+"\n"; }}, require("Storage").open("testfile","w"));

// Pipe a StorageFile straight to the Bluetooth UART E.pipe(require("Storage").open("testfile","r"), Bluetooth);

// Pipe a normal file in Storage (not StorageFile) straight to the Bluetooth UART E.pipe(require("Storage").read("blob.txt"), Bluetooth);

// Pipe a normal file in Storage as a response to an HTTP request function onPageRequest(req, res) { res.writeHead(200, {'Content-Type': 'text/plain'}); E.pipe(require("Storage").read("webpage.txt"), res); } require("http").createServer(onPageRequest).listen(80); ```

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

Forces a hard reboot of the microcontroller - as close as possible to if the reset pin had been toggled.

Note: This is different to reset(), which performs a software reset of Espruino (resetting the interpreter and pin states, but not all the hardware)

Reverse the 8 bits in a byte, swapping MSB and LSB.

For example, E.reverseByte(0b10010000) == 0b00001001.

Note that you can reverse all the bytes in an array with:

arr =
arr.map(E.reverseByte)

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

This writes JavaScript code into Espruino's flash memory, to be executed on startup. It differs from save() in that save() saves the whole state of the interpreter, whereas this just saves JS code that is executed at boot.

Code will be executed before onInit() and E.on('init', ...).

If alwaysExec is true, the code will be executed even after a call to reset(). This is useful if you're making something that you want to program, but you want some code that is always built in (for instance setting up a display or keyboard).

To remove boot code that has been saved previously, use E.setBootCode("")

Note: this removes any code that was previously saved with save()

This sets the clock frequency of Espruino's processor. It will return 0 if it is unimplemented or the clock speed cannot be changed.

Note: On pretty much all boards, UART, SPI, I2C, PWM, etc will change frequency and will need setting up again in order to work.

STM32F4

Options is of the form { M: int, N: int, P: int, Q: int } - see the 'Clocks' section of the microcontroller's reference manual for what these mean.

• System clock = 8Mhz * N / ( M * P )
• USB clock (should be 48Mhz) = 8Mhz * N / ( M * Q )

Optional arguments are:

• latency - flash latency from 0..15
• PCLK1 - Peripheral clock 1 divisor (default: 2)
• PCLK2 - Peripheral clock 2 divisor (default: 4)

The Pico's default is {M:8, N:336, P:4, Q:7, PCLK1:2, PCLK2:4}, use

{M:8,
N:336, P:8, Q:7, PCLK:1, PCLK2:2}

On STM32F4 boards (e.g. Espruino Pico), the USB clock needs to be kept at 48Mhz or USB will fail to work. You'll also experience USB instability if the processor clock falls much below 48Mhz.

ESP8266

Just specify an integer value, either 80 or 160 (for 80 or 160Mhz)

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

Changes the device that the JS console (otherwise known as the REPL) is attached to. If the console is on a device, that device can be used for programming Espruino.

Rather than calling Serial.setConsole you can call E.setConsole("DeviceName").

This is particularly useful if you just want to remove the console. E.setConsole(null) will make the console completely inaccessible.

device may be "Serial1","USB","Bluetooth","Telnet","Terminal", any other hardware Serial device, or null to disable the console completely.

options is of the form:

{
  force : bool // default false, force the console onto this device so it does not move
               //   if false, changes in connection state (e.g. USB/Bluetooth) can move
               //   the console automatically.
}

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

Set the daylight savings time parameters to be used with Date objects.

The parameters are - dstOffset: The number of minutes daylight savings time adds to the clock (usually 60) - set to 0 to disable DST - timezone: The time zone, in minutes, when DST is not in effect - positive east of Greenwich - startDowNumber: The index of the day-of-week in the month when DST starts - 0 for first, 1 for second, 2 for third, 3 for fourth and 4 for last - startDow: The day-of-week for the DST start calculation - 0 for Sunday, 6 for Saturday - startMonth: The number of the month that DST starts - 0 for January, 11 for December - startDayOffset: The number of days between the selected day-of-week and the actual day that DST starts - usually 0 - startTimeOfDay: The number of minutes elapsed in the day before DST starts - endDowNumber: The index of the day-of-week in the month when DST ends - 0 for first, 1 for second, 2 for third, 3 for fourth and 4 for last - endDow: The day-of-week for the DST end calculation - 0 for Sunday, 6 for Saturday - endMonth: The number of the month that DST ends - 0 for January, 11 for December - endDayOffset: The number of days between the selected day-of-week and the actual day that DST ends - usually 0 - endTimeOfDay: The number of minutes elapsed in the day before DST ends

To determine what the dowNumber, dow, month, dayOffset, timeOfDay parameters should be, start with a sentence of the form "DST starts on the last Sunday of March (plus 0 days) at 03:00". Since it's the last Sunday, we have startDowNumber = 4, and since it's Sunday, we have startDow = 0. That it is March gives us startMonth = 2, and that the offset is zero days, we have startDayOffset = 0. The time that DST starts gives us startTimeOfDay = 3*60.

"DST ends on the Friday before the second Sunday in November at 02:00" would give us endDowNumber=1, endDow=0, endMonth=10, endDayOffset=-2 and endTimeOfDay=120.

Using Ukraine as an example, we have a time which is 2 hours ahead of GMT in winter (EET) and 3 hours in summer (EEST). DST starts at 03:00 EET on the last Sunday in March, and ends at 04:00 EEST on the last Sunday in October. So someone in Ukraine might call E.setDST(60,120,4,0,2,0,180,4,0,9,0,240);

Examples:

// United Kingdom
E.setDST(60,0,4,0,2,0,60,4,0,9,0,120);
// California, USA
E.setDST(60,-480,1,0,2,0,120,0,0,10,0,120);
// Or adjust -480 (-8 hours) for other US states
// Ukraine
E.setDST(60,120,4,0,2,0,180,4,0,9,0,240);

Note: This is not compatible with E.setTimeZone(). Calling E.setTimeZone() after this will disable DST.

Note: This is not available in ESPRNODAYLIGHT_SAVING

Set the Espruino interpreter flags that control the way it handles your JavaScript code.

Run E.getFlags() and check its description for a list of available flags and their values.

Set a password on the console (REPL). When powered on, Espruino will then demand a password before the console can be used. If you want to lock the console immediately after this you can call E.lockConsole()

To remove the password, call this function with no arguments.

Note: There is no protection against multiple password attempts, so someone could conceivably try every password in a dictionary.

Note: This password is stored in memory in plain text. If someone is able to execute arbitrary JavaScript code on the device (e.g., you use eval on input from unknown sources) or read the device's firmware then they may be able to obtain it.

Set the time zone to be used with Date objects.

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

Time can be set with setTime.

Note: If daylight savings time rules have been set with E.setDST(), calling E.setTimeZone() will remove them and move back to using a static timezone that doesn't change based on the time of year.

Set the seed for the random number generator used by Math.random().

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

When using events with X.on('foo', function() { ... }) and then X.emit('foo') you might want to stop subsequent event handlers from being executed.

Calling this function doing the execution of events will ensure that no subsequent event handlers are executed.

var X = {}; // in Espruino all objects are EventEmitters
X.on('foo', function() { print("A"); })
X.on('foo', function() { print("B"); E.stopEventPropagation(); })
X.on('foo', function() { print("C"); })
X.emit('foo');
// prints A,B but not C

Sum the contents of the given Array, String or ArrayBuffer and return the result

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

Create an ArrayBuffer from the given string. This is done via a reference, not a copy - so it is very fast and memory efficient.

Note that this is an ArrayBuffer, not a Uint8Array. To get one of those, do: new Uint8Array(E.toArrayBuffer('....')).

Returns a Flat String representing the data in the arguments, or undefined if one can't be allocated.

This provides the same behaviour that E.toString had in Espruino before 2v18 - see E.toString for more information.

This performs the same basic function as JSON.stringify, however JSON.stringify adds extra characters to conform to the JSON spec which aren't required if outputting JS.

E.toJS will also stringify JS functions, whereas JSON.stringify ignores them.

For example:

• JSON.stringify({a:1,b:2}) == '{"a":1,"b":2}'
• E.toJS({a:1,b:2}) == '{a:1,b:2}'

Note: Strings generated with E.toJS can't be reliably parsed by JSON.parse - however they are valid JS so will work with eval (but this has security implications if you don't trust the source of the string).

On the desktop JSON5 parsers will parse the strings produced by E.toJS without trouble.

Returns a String representing the data in the arguments.

This creates a string from the given arguments in the same way as E.toUint8Array. If each argument is:

• A String or an Array, each element is traversed and added as an 8 bit character
• {data : ..., count : N} causes data to be repeated count times
• {callback : fn} calls the function and adds the result
• Anything else is converted to a character directly.

In the case where there's one argument which is an 8 bit typed array backed by a flat string of the same length, the backing string will be returned without doing a copy or other allocation. The same applies if there's a single argument which is itself a flat string.

```JS E.toString(0,1,2,"Hi",3) "\0\1\2Hi\3" E.toString(1,2,{data:[3,4], count:4},5,6) "\1\2\3\4\3\4\3\4\3\4\5\6"

E.toString(1,2,{callback : () => "Hello World"},5,6) ="\1\2Hello World\5\6" ```

Note: Prior to Espruino 2v18 E.toString would always return a flat string, or would return undefined if one couldn't be allocated. Now, it will return a normal (fragmented) String if a contiguous chunk of memory cannot be allocated. You can still check if the returned value is a Flat string using E.getAddressOf(str, true)!=0, or can use E.toFlatString instead.

This event is called when a full touchscreen device on an Espruino is interacted with.

Note: This event is not implemented on Bangle.js because it only has a two area touchscreen.

To use the touchscreen to draw lines, you could do:

var last;
E.on('touch',t=>{
  if (last) g.lineTo(t.x, t.y);
  else g.moveTo(t.x, t.y);
  last = t.b;
});

This creates a Uint8Array from the given arguments. These are handled as follows:

• Number -> read as an integer, using the lowest 8 bits
• String -> use each character's numeric value (e.g. String.charCodeAt(...))
• Array -> Call itself on each element
• ArrayBuffer or Typed Array -> use the lowest 8 bits of each element
• Object:
  • {data:..., count: int} -> call itself object.count times, on object.data
  • {callback : function} -> call the given function, call itself on return value

For example:

E.toUint8Array([1,2,3])
=new Uint8Array([1, 2, 3])
E.toUint8Array([1,{data:2,count:3},3])
=new Uint8Array([1, 2, 2, 2, 3])
E.toUint8Array("Hello")
=new Uint8Array([72, 101, 108, 108, 111])
E.toUint8Array(["hi",{callback:function() { return [1,2,3] }}])
=new Uint8Array([104, 105, 1, 2, 3])

Work out the variance of the contents of the given Array, String or ArrayBuffer and return the result. This is equivalent to

v=0;for (i in arr)
v+=Math.pow(mean-arr[i],2)

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

The base class for runtime errors

Creates an Error object

This module allows you to read and write the nonvolatile flash memory of your device.

Also see the Storage library, which provides a safer file-like interface to nonvolatile storage.

It should be used with extreme caution, as it is easy to overwrite parts of Flash memory belonging to Espruino or even its bootloader. If you damage the bootloader then you may need external hardware such as a USB-TTL converter to restore it. For more information on restoring the bootloader see

Advanced
Reflashing

To see which areas of memory you can and can't overwrite, look at the values reported by process.memory().

Note: On Nordic platforms there are checks in place to help you avoid 'bricking' your device be damaging the bootloader. You can disable these with E.setFlags({unsafeFlash:1})

Erase a page of flash memory

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

This method returns an array of objects of the form {addr : #, length : #}, representing contiguous areas of flash memory in the chip that are not used for anything.

The memory areas returned are on page boundaries. This means that you can safely erase the page containing any address here, and you won't risk deleting part of the Espruino firmware.

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

Returns the start and length of the flash page containing the given address.

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

Read flash memory from the given address

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

Write data into memory at the given address

In flash memory you may only turn bits that are 1 into bits that are 0. If you're writing data into an area that you have already written (so read doesn't return all 0xFF) you'll need to call erasePage to clear the entire page.

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

This is the built-in JavaScript class for a typed array of 32 bit floating point values.

Instantiate this in order to efficiently store arrays of data (Espruino's normal arrays store data in a map, which is inefficient for non-sparse arrays).

Arrays of this type include all the methods from ArrayBufferView

Create a typed array based on the given input. Either an existing Array Buffer, an Integer as a Length, or a simple array. If an ArrayBufferView (e.g. Uint8Array rather than ArrayBuffer) is given, it will be completely copied rather than referenced.

This is the built-in JavaScript class for a typed array of 64 bit floating point values.

Instantiate this in order to efficiently store arrays of data (Espruino's normal arrays store data in a map, which is inefficient for non-sparse arrays).

Arrays of this type include all the methods from ArrayBufferView

Create a typed array based on the given input. Either an existing Array Buffer, an Integer as a Length, or a simple array. If an ArrayBufferView (e.g. Uint8Array rather than ArrayBuffer) is given, it will be completely copied rather than referenced.

Pipe this file to a destination stream (object which has a .write(data) method).

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

This is the built-in class for Functions

This executes the function with the supplied 'this' argument and parameters

This executes the function with the supplied 'this' argument and parameters

This executes the function with the supplied 'this' argument and parameters

Creates a function

This replaces the function with the one in the argument - while keeping the old function's scope. This allows inner functions to be edited, and is used when edit() is called on an inner function.

This class provides Graphics operations that can be applied to a surface.

Use Graphics.createXXX to create a graphics object that renders in the way you want. See the Graphics page for more information.

Note: On boards that contain an LCD, there is a built-in g object of type Graphics. For instance to draw a line you'd type: g.drawLine(0,0,100,100)

Create a Windows BMP file from this Graphics instance, and return it as a String.

Note: This is not available in devices with low flash memory or 'Original' Espruino boards

Return this Graphics object as an Image that can be used with Graphics.drawImage. Check out the Graphics reference page for more information on images.

Will return undefined if data can't be allocated for the image.

The image data itself will be referenced rather than copied if:

• An image object was requested (not string)
• The Graphics instance was created with Graphics.createArrayBuffer
• Is 8 bpp OR the {msb:true} option was given
• No other format options (zigzag/etc) were given

Otherwise data will be copied, which takes up more space and may be quite slow.

If the Graphics object contains transparent or palette fields, as you might find in an image, those will be included in the generated image too.

var gfx = Graphics.createArrayBuffer(8,8,1);
gfx.transparent = 0;
gfx.drawString("X",0,0);
var im = gfx.asImage("string");

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

Create a URL of the form data:image/bmp;base64,... that can be pasted into the browser.

The Espruino Web IDE can detect this data on the console and render the image inline automatically.

Note: This is not available in devices with low flash memory or 'Original' Espruino boards

Blit one area of the screen (x1,y1 w,h) to another (x2,y2 w,h)

g.blit({
  x1:0, y1:0,
  w:32, h:32,
  x2:100, y2:100,
  setModified : true // should we set the modified area?
});

Note: This uses repeated pixel reads and writes, so will not work on platforms that don't support pixel reads.

Note: This is not available in devices with low flash memory or 'Original' Espruino boards

On Graphics instances with an offscreen buffer, this is an ArrayBuffer that provides access to the underlying pixel data.

g=Graphics.createArrayBuffer(8,8,8)
g.drawLine(0,0,7,7)
print(new Uint8Array(g.buffer))
new Uint8Array([
255, 0, 0, 0, 0, 0, 0, 0,
0, 255, 0, 0, 0, 0, 0, 0,
0, 0, 255, 0, 0, 0, 0, 0,
0, 0, 0, 255, 0, 0, 0, 0,
0, 0, 0, 0, 255, 0, 0, 0,
0, 0, 0, 0, 0, 255, 0, 0,
0, 0, 0, 0, 0, 0, 255, 0,
0, 0, 0, 0, 0, 0, 0, 255])

Clear the LCD with the Background Color

Fill a rectangular area in the Background Color

On devices with enough memory, you can specify {x,y,x2,y2,r} as the first argument, which allows you to draw a rounded rectangle.

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

Create a Graphics object that renders to an Array Buffer. This will have a field called 'buffer' that can get used to get at the buffer itself

Create a Graphics object that renders by calling a JavaScript callback function to draw pixels

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

Create a simple Black and White image for use with Graphics.drawImage.

Use as follows:

var img = Graphics.createImage(`
XXXXXXXXX
X       X
X   X   X
X   X   X
X       X
XXXXXXXXX
`);
g.drawImage(img, x,y);
var img = Graphics.createImage(`
.....
.XXX.
.X.X.
.XXX.
.....
`);
g.drawImage(img, x,y);

If the characters at the beginning and end of the string are newlines, they will be ignored. Spaces are treated as 0, and any other character is a 1

Note: This is not available in devices with low flash memory or 'Original' Espruino boards

Draw an unfilled circle 1px wide in the Foreground Color

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

Draw an ellipse in the Foreground Color

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

Image can be:

• An object with the following fields

  { width : int, height : int, bpp :
  optional int, buffer : ArrayBuffer/String, transparent: optional int,
  palette : optional Uint16Array(2/4/16) }

  . bpp = bits per pixel (default is 1), transparent (if defined) is the colour that will be treated as transparent, and palette is a color palette that each pixel will be looked up in first
• A String where the the first few bytes are: width,height,bpp,[transparent,]image_bytes.... If a transparent colour is specified the top bit of bpp should be set.
• An ArrayBuffer Graphics object (if bpp<8, msb:true must be set) - this is disabled on devices without much flash memory available. If a Graphics object is supplied, it can also contain transparent/palette fields as if it were an image.

See https://www.espruino.com/Graphics#images-bitmaps for more information about image formats.

Draw an image at the specified position.

• If the image is 1 bit, the graphics foreground/background colours will be used.
• If img.palette is a Uint16Array or 2/4/16 elements, color data will be looked from the supplied palette
• On Bangle.js, 2 bit images blend from background(0) to foreground(1) colours
• On Bangle.js, 4 bit images use the Apple Mac 16 color palette
• On Bangle.js, 8 bit images use the Web Safe 216 color palette
• Otherwise color data will be copied as-is. Bitmaps are rendered MSB-first

If options is supplied, drawImage will allow images to be rendered at any scale or angle. If options.rotate is set it will center images at x,y. options must be an object of the form:

{
  rotate : float, // the amount to rotate the image in radians (default 0)
  scale : float, // the amount to scale the image up (default 1)
  frame : int    // if specified and the image has frames of data
                 //  after the initial frame, draw one of those frames from the image
  filter : bool  // (2v19+) when set, if scale<0.75 perform 2x2 supersampling to smoothly downscale the image
}

For example:

// In the top left of the screen
g.drawImage(img,0,0);
// In the top left of the screen, twice as big
g.drawImage(img,0,0,{scale:2});
// In the center of the screen, twice as big, 45 degrees
g.drawImage(img, g.getWidth()/2, g.getHeight()/2,
            {scale:2, rotate:Math.PI/4});

Draw a line between x1,y1 and x2,y2 in the current foreground color

Draw a polyline (lines between each of the points in poly) in the current foreground color

Note: there is a limit of 64 points (128 XY elements) for polygons

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

Draw an unfilled rectangle 1px wide in the Foreground Color

Draw a string of text in the current font.

g.drawString("Hello World", 10, 10);

Images may also be embedded inside strings (e.g. to render Emoji or characters not in the current font). To do this, just add 0 then the image string (about Images) For example:

g.drawString("Hi \0\7\5\1\x82 D\x17\xC0");
// draws:
// # #  #      #     #
// # #            #
// ### ##         #
// # #  #      #     #
// # # ###      #####

Output this image as a bitmap URL of the form data:image/bmp;base64,.... The Espruino Web IDE will detect this on the console and will render the image inline automatically.

This is identical to console.log(g.asURL()) - it is just a convenient function for easy debugging and producing screenshots of what is currently in the Graphics instance.

Note: This may not work on some bit depths of Graphics instances. It will also not work for the main Graphics instance of Bangle.js 1 as the graphics on Bangle.js 1 are stored in write-only memory.

Note: This is not available in devices with low flash memory or 'Original' Espruino boards

Draw a filled circle in the Foreground Color

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

Draw a filled ellipse in the Foreground Color

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

Draw a filled polygon in the current foreground color.

g.fillPoly([
  16, 0,
  31, 31,
  26, 31,
  16, 12,
  6, 28,
  0, 27 ]);

This fills from the top left hand side of the polygon (low X, low Y) down to but not including the bottom right. When placed together polygons will align perfectly without overdraw - but this will not fill the same pixels as drawPoly (drawing a line around the edge of the polygon).

Note: there is a limit of 64 points (128 XY elements) for polygons

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

Fill a rectangular area in the Foreground Color

On devices with enough memory, you can specify {x,y,x2,y2,r} as the first argument, which allows you to draw a rounded rectangle.