Espruino Software Reference

Note: This function is only available on the BBC micro:bit board

Get the current acceleration of the micro:bit from the on-board accelerometer

Get the analog 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"

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

Objects can contain:

• freq - pulse frequency in Hz, eg. 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

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 timers and intervals are stopped

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 timers and intervals are stopped

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

Note: This function is only available on the BBC micro:bit board

Get the current compass position for the micro:bit from the on-board magnetometer

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.

eg. 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 (eg. [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.

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

If pin argument is an array of pins (eg. [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.

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

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.

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

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

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

The first I2C port

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

The second I2C port

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

The third I2C port

Note: This is only available in devices with more than 3 I2C peripherals

Is the parameter a finite num,ber 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 ... });. This will then be automatically executed by Espruino every time it starts.

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 ... });. This will then be automatically executed by Espruino every time it starts.

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

The pin marked SDA on the Arduino pin footprint. This is connected directly to pin A5.

Note: This is only available in Pixl.js boards

The pin marked SDA on the Arduino pin footprint. This is connected directly to pin A4.

Note: This is only available in Pixl.js boards

The first Serial (USART) port

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

The second Serial (USART) port

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

The third Serial (USART) port

Note: This is only available in devices with more than 3 USART peripherals

The fourth Serial (USART) port

Note: This is only available in devices with more than 4 USART peripherals

The fifth Serial (USART) port

Note: This is only available in devices with more than 5 USART peripherals

The sixth Serial (USART) port

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

Set whether we can enter deep sleep mode, which reduces power consumption to around 100uA. This only works on STM32 Espruino Boards (nRF52 boards sleep automatically).

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

Note: This is only available in STM32 devices (including Espruino Original, Pico and WiFi) and EFM32 devices

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 (to the nearest second).

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

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
   data : pin
}

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

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' });. This will only be called on the falling edge of the pulse, but will be able to measure the width of the pulse because e.lastTime is the time of the rising edge.

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

Note: This function is only available on the BBC micro:bit board

Show an image on the in-built 5x5 LED screen.

Image can be:

• A number where each bit represents a pixel (so 25 bits). eg. 5 or 0x1FFFFFF
• A string, eg: show("10001"). Newlines are ignored, and anything that is not a space or 0 is treated as a 1.
• An array of 4 bytes (more will be ignored), eg show([1,2,3,0])

For instance the following works for images:

show("#   #"+
     "  #  "+
     "  #  "+
     "#   #"+
     " ### ")

This means you can also use Espruino's graphics library:

var g = Graphics.createArrayBuffer(5,5,1)
g.drawString("E",0,0)
show(g.buffer)

The first SPI port

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

The second SPI port

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

The third SPI port

Note: This is only available in devices with more than 3 SPI peripherals

A telnet serial device that maps to the built-in telnet console server (devices that have built-in wifi only).

Note: This is only available in devices with Telnet enabled (Linux, ESP8266 and ESP32)

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 USB Serial port

Note: This is only available in devices with USB

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 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. eg. [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) for each element in the array, and finally return previousValue.

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 the index of the value in the array, or -1

Join all elements of this array together into one string, using 'separator' between them. eg. [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, eg. [].map.call(myArray, x=>x+1)

Execute previousValue=initialValue and then previousValue = callback(previousValue, currentValue, index, array) for each element in the array, and finally return previousValue.

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

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

Note: This is only available in NRF52 devices (like Puck.js, Pixl.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 and MDBT42Q)

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

Respond with BluetoothDevice.sendPasskey() 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 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 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}, and BluetoothRemoteGATTCharacteristic.value will then contain the new value (as a DataView).

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

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

Stop notifications (that were requested with BluetoothRemoteGATTCharacteristic.startNotifications)

Note: This is only available in NRF52 devices (like Puck.js, Pixl.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 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: This is only available in NRF52 devices (like Puck.js, Pixl.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 and MDBT42Q) and ESP32 boards

See NRF.connect for usage examples.

Note: This is only available in NRF52 devices (like Puck.js, Pixl.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 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 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 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 and MDBT42Q) and ESP32 boards

Creates a boolean

Initialise the CC3000 and return a WLAN object

An Object that contains functions for writing to the interactive console

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.

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)

Password-Based Key Derivation Function 2 algorithm, using SHA512

Note: This is only available in devices with TLS and SSL support (Espruino Pico and Espruino WiFi only)

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)

Performs a SHA384 hash and returns the result as a 48 byte ArrayBuffer

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

Performs a SHA512 hash and returns the result as a 64 byte ArrayBuffer

Note: This is only available in devices that support SHA512 (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

Creates a date object

Day of the month 1..31

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

The year, eg. 2014

0..23

0..999

0..59

Month of the year 0..11

0..59

Return the number of milliseconds since 1970

This returns Espruino's time-zone offset from UTC, in minutes.

This is set with E.setTimeZone and is System-wide. The value returned has nothing to do with the instance of Date that it is called on.

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)

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, eg: 2014-06-20T14:52:20.123Z

Note: This always assumes a timezone of GMT

Converts to a String, eg: Fri Jun 20 2014 14:52:20 GMT+0000

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

Converts to a String, eg: 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

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

Setup the filesystem so that subsequent calls to E.openFile and require('fs').* will use an SD card on the supplied SPI device and pin.

It can even work using software SPI - for instance:

// DI/CMD = C7
// DO/DAT0 = C8
// CK/CLK = C9
// CD/CS/DAT3 = C6
var spi = new SPI();
spi.setup({mosi:C7, miso:C8, sck:C9});
E.connectSDCard(spi, C6);
console.log(require("fs").readdirSync());

See the page on File IO for more information.

Note: We'd strongly suggest you add a pullup resistor from CD/CS pin to 3.3v. It is good practise to avoid accidental writes before Espruino is initialised, and some cards will not work reliably without one.

Note: If you want to remove an SD card after you have started using it, you must call E.unmountSD() or you may cause damage to the card.

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

Show fragmentation

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 is not available in release builds

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

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 release builds

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 and nRF5x devices (all official Espruino boards).

NOTE: On STM32 (Pico, WiFi, Original) with setDeepSleep(1), or nRF52 (Puck, Pixl, MDBT42) 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.

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

Change the paramters used for the flash filesystem. The default address is the last 1Mb of 4Mb Flash, 0x300000, with total size of 1Mb.

Before first use the media needs to be formatted.

fs=require("fs");
try {
  fs.readdirSync();
 } catch (e) { //'Uncaught Error: Unable to mount media : NO_FILESYSTEM'
  console.log('Formatting FS - only need to do once');
  E.flashFatFS({ format: true });
}
fs.writeFileSync("bang.txt", "This is the way the world ends\nnot with a bang but a whimper.\n");
fs.readdirSync();

This will create a drive of 100 * 4096 bytes at 0x300000. Be careful with the selection of flash addresses as you can overwrite firmware! You only need to format once, as each will erase the content.

E.flashFatFS({ addr:0x300000,sectors:100,format:true });

Note: This is only available in devices with filesystem in Flash support enabled (ESP32 only)

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

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.

Gets the RTC's current prescaler value if calibrate is undefined or false.

If calibrate is true, the low speed oscillator's speed is calibrated against the high speed oscillator (usually +/- 20 ppm) and a suggested value to be fed into E.setRTCPrescaler(...) is returned.

See E.setRTCPrescaler for more information.

Note: This is only available in Espruino Pico boards and Espruino WiFi boards and 'Original' Espruino boards

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's 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 STM32's internal thermistor to work out the temperature.

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

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, xoring 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.

Interpolate between two adjacent values in the Typed Array

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

Interpolate between four adjacent values in the Typed Array, in 2D.

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

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 actually references a specific memory address. It can be used in order to use sections of Flash memory directly in Espruino (for example to execute code straight from flash memory with eval(E.memoryArea( ... )))

Note: This is only tested on STM32-based platforms (Espruino Original and Espruino Pico) at the moment.

ADVANCED: This is a great way to crash Espruino if you're not sure what you are doing

Create a native function that executes the code at the given address. Eg. 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.

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.

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

Open a file

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} to halve the system clock speed while keeping the peripherals running at the same speed (omitting PCLK1/2 will lead to the peripherals changing speed too).

On STM32F4 boards (eg. 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

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 (eg, you use eval on input from unknown sources) or read the device's firmware then they may be able to obtain it.

Sets the RTC's prescaler's maximum value. This is the counter that counts up on each oscillation of the low speed oscillator. When the prescaler counts to the value supplied, one second is deemed to have passed.

By default this is set to the oscillator's average speed as specified in the datasheet, and usually that is fine. However on early Espruino Pico boards the STM32F4's internal oscillator could vary by as much as 15% from the value in the datasheet. In that case you may want to alter this value to reflect the true RTC speed for more accurate timekeeping.

To change the RTC's prescaler value to a computed value based on comparing against the high speed oscillator, just run the following command, making sure it's done a few seconds after the board starts up:

E.setRTCPrescaler(E.getRTCPrescaler(true));

When changing the RTC prescaler, the RTC 'follower' counters are reset and it can take a second or two before readings from getTime are stable again.

To test, you can connect an input pin to a known frequency square wave and then use setWatch. If you don't have a frequency source handy, you can check against the high speed oscillator:

// connect pin B3 to B4
analogWrite(B3, 0.5, {freq:0.5});
setWatch(function(e) {
  print(e.time - e.lastTime);
}, B4, {repeat:true});

Note: This is only used on official Espruino boards containing an STM32 microcontroller. Other boards (even those using an STM32) don't use the RTC and so this has no effect.

Note: This is only available in Espruino Pico boards and Espruino WiFi boards and 'Original' Espruino boards

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.

USB HID will only take effect next time you unplug and re-plug your Espruino. If you're disconnecting it from power you'll have to make sure you have save()d after calling this function.

Note: This is only available in devices that support USB HID (Espruino Pico and Espruino WiFi)

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

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

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('....')).

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 'flat' string representing the data in the arguments, or return undefined if a flat string cannot be created.

This creates a string from the given arguments. If an argument is a String or an Array, each element is traversed and added as an 8 bit character. If it is anything else, it 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.

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 (eg. 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])

Unmount the SD card, so it can be removed. If you remove the SD card without calling this you may cause corruption, and you will be unable to access another SD card until you reset Espruino or call E.unmountSD().

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

Put device in deepsleep state for "us" microseconds.

Switches Bluetooth off/on, removes saved code from Flash, resets the board, and on restart creates jsVars depending on available heap (actual additional 1800)

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

Switches Wifi off/on, removes saved code from Flash, resets the board, and on restart creates jsVars depending on available heap (actual additional 3900)

Returns an object that contains details about the state of the ESP32 with the following fields:

• sdkVersion - Version of the SDK.
• freeHeap - Amount of free heap in bytes.
• BLE - Status of BLE, enabled if true.
• Wifi - Status of Wifi, enabled if true.
• minHeap - Minimum heap, calculated by heap_caps_get_minimum_free_size

Perform a hardware reset/reboot of the ESP32.

The ESP8266 library is specific to the ESP8266 version of Espruino, i.e., running Espruino on an ESP8266 module (not to be confused with using the ESP8266 as Wifi add-on to an Espruino board). This library contains functions to handle ESP8266-specific actions. For example: var esp8266 = require('ESP8266'); esp8266.reboot(); performs a hardware reset of the module.

Put the ESP8266 into 'deep sleep' for the given number of microseconds, reducing power consumption drastically.

meaning of option values:

0 - the 108th Byte of init parameter decides whether RF calibration will be performed or not.

1 - run RF calibration after waking up. Power consumption is high.

2 - no RF calibration after waking up. Power consumption is low.

4 - no RF after waking up. Power consumption is the lowest.

Note: unlike normal Espruino boards' 'deep sleep' mode, ESP8266 deep sleep actually turns off the processor. After the given number of microseconds have elapsed, the ESP8266 will restart as if power had been turned off and then back on. All contents of RAM will be lost. Connect GPIO 16 to RST to enable wakeup.

Special: 0 microseconds cause sleep forever until external wakeup RST pull down occurs.

Dumps info about all sockets to the log. This is for troubleshooting the socket implementation.

Note: This is deprecated. Use require("Flash").getFree()

At boot time the esp8266's firmware captures the cause of the reset/reboot. This function returns this information in an object with the following fields:

• reason: "power on", "wdt reset", "exception", "soft wdt", "restart", "deep sleep", or "reset pin"
• exccause: exception cause
• epc1, epc2, epc3: instruction pointers
• excvaddr: address being accessed
• depc: (?)

Returns an object that contains details about the state of the ESP8266 with the following fields:

• sdkVersion - Version of the SDK.
• cpuFrequency - CPU operating frequency in Mhz.
• freeHeap - Amount of free heap in bytes.
• maxCon - Maximum number of concurrent connections.
• flashMap - Configured flash size&map: '512KB:256/256' .. '4MB:512/512'
• flashKB - Configured flash size in KB as integer
• flashChip - Type of flash chip as string with manufacturer & chip, ex: '0xEF 0x4016`

Enable or disable the logging of debug information. A value of true enables debug logging while a value of false disables debug logging. Debug output is sent to UART1 (gpio2).