Espruino Hardware Reference

The Espruino Software will run on a variety of boards. However the official boards below have been specially designed to complement our software, and are the only boards that we actively support. Please click on the thumbnails below to see diagrams of each board with their pins and capabilities.

Official Boards

Original Espruino
Original Espruino
Espruino Pico
Espruino Pico
Espruino WiFi
Espruino WiFi
Puck.js
Puck.js

Unofficial boards

 


Espruino Software Reference

Version 1v89

Contents

Globals

AES

Array

ArrayBuffer

ArrayBufferView

BluetoothDevice

BluetoothRemoteGATTCharacteristic

BluetoothRemoteGATTServer

BluetoothRemoteGATTService

Boolean

CC3000

console

crypto

Date

E

Error

ESP8266

Ethernet

File

Flash

Float32Array

Float64Array

fs

Function

Graphics

HASH

hashlib

http

httpCRq

httpCRs

httpSRq

httpSRs

httpSrv

I2C

Int16Array

Int32Array

Int8Array

InternalError

JSON

Math

Modules

net

NetworkJS

NodeMCU

NRF

Nucleo

Number

Object

OneWire

Pin

process

Promise

Puck

ReferenceError

Serial

Server

Socket

SPI

String

SyntaxError

TelnetServer

tls

tv

TypeError

Uint16Array

Uint32Array

Uint8Array

Uint8ClampedArray

url

Waveform

Wifi

WIZnet

WLAN

Detail

Global Functions

(top)

Methods and Fields

function acceleration

(top)

Call type:

function acceleration()

Description

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

Returns

An object with x, y, and z fields in it

function analogRead

(top)

Call type:

function analogRead(pin)

Description

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"

Parameters

pin - The pin to use
You can find out which pins to use by looking at your board's reference page and searching for pins with the ADC markers.

Returns

The analog Value of the Pin between 0 and 1

Examples

This function is used in the following places in Espruino's documentation

function analogWrite

(top)

Call type:

function analogWrite(pin, value, options)

Description

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 available.
  • forceSoft - boolean, If true software PWM is used even

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

Parameters

pin - The pin to use
You can find out which pins to use by looking at your board's reference page and searching for pins with the PWM or DAC markers.

value - A value between 0 and 1

options - An object containing options for analog output - see below

Examples

This function is used in the following places in Espruino's documentation

variable arguments

(top)

Call type:

variable arguments

Description

A variable containing the arguments given to the function

Returns

An array containing all the arguments given to the function

function atob

(top)

Call type:

function atob(binaryData)

Description

Decode the supplied base64 string into a normal string Note: This is only available in some devices: not devices with low flash memory

Parameters

binaryData - A string of base64 data to decode

Returns

A string containing the decoded data

Examples

This function is used in the following places in Espruino's documentation

function btoa

(top)

Call type:

function btoa(binaryData)

Description

Encode the supplied string (or array) into a base64 string Note: This is only available in some devices: not devices with low flash memory

Parameters

binaryData - A string of data to encode

Returns

A base64 encoded string

function changeInterval

(top)

Call type:

function changeInterval(id, time)

Description

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.

Parameters

id - The id returned by a previous call to setInterval

time - The new time period in ms

Examples

This function is used in the following places in Espruino's documentation

function clearInterval

(top)

Call type:

function clearInterval(id)

Description

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

Parameters

id - The id returned by a previous call to setInterval

Examples

This function is used in the following places in Espruino's documentation

function clearTimeout

(top)

Call type:

function clearTimeout(id)

Description

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

Parameters

id - The id returned by a previous call to setTimeout

Examples

This function is used in the following places in Espruino's documentation

function clearWatch

(top)

Call type:

function clearWatch(id)

Description

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

Parameters

id - The id returned by a previous call to setWatch

Examples

This function is used in the following places in Espruino's documentation

function compass

(top)

Call type:

function compass()

Description

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

Returns

An object with x, y, and z fields in it

Examples

This function is used in the following places in Espruino's documentation

function decodeURIComponent

(top)

Call type:

function decodeURIComponent(str)

Description

Convert any groups of characters of the form '%ZZ', into characters with hex code '0xZZ' Note: This is only available in some devices: not devices with low flash memory

Parameters

str - A string to decode from a URI

Returns

A string containing the decoded data

function digitalPulse

(top)

Call type:

function digitalPulse(pin, value, time)

Description

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.

Parameters

pin - The pin to use

value - Whether to pulse high (true) or low (false)

time - A time in milliseconds, or an array of times (in which case a square wave will be output starting with a pulse of 'value')

Examples

This function is used in the following places in Espruino's documentation

function digitalRead

(top)

Call type:

function digitalRead(pin)

Description

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

Parameters

pin - The pin to use

Returns

The digital Value of the Pin

Examples

This function is used in the following places in Espruino's documentation

function digitalWrite

(top)

Call type:

function digitalWrite(pin, value)

Description

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.

Parameters

pin - The pin to use

value - Whether to pulse high (true) or low (false)

Examples

This function is used in the following places in Espruino's documentation

function dump

(top)

Call type:

function dump()

Description

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 only available in some devices: not devices with low flash memory

function echo

(top)

Call type:

function echo(echoOn)

Description

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

Parameters

echoOn -

function edit

(top)

Call type:

function edit(funcName)

Description

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.

Parameters

funcName - The name of the function to edit (either a string or just the unquoted name)

Examples

This function is used in the following places in Espruino's documentation

function encodeURIComponent

(top)

Call type:

function encodeURIComponent(str)

Description

Convert a string with any character not alphanumeric or - _ . ! ~ * ' ( ) converted to the form %XY where XY is its hexadecimal representation Note: This is only available in some devices: not devices with low flash memory

Parameters

str - A string to encode as a URI

Returns

A string containing the encoded data

Examples

This function is used in the following places in Espruino's documentation

function eval

(top)

Call type:

function eval(code)

Description

Evaluate a string containing JavaScript code

Parameters

code -

Returns

The result of evaluating the string

Examples

This function is used in the following places in Espruino's documentation

function getPinMode

(top)

Call type:

function getPinMode(pin)

Description

Return the current mode of the given pin. See pinMode for more information on returned values. Note: This is only available in some devices: not devices with low flash memory

Parameters

pin - The pin to check

Returns

The pin mode, as a string

function getSerial

(top)

Call type:

function getSerial()

Description

Get the serial number of this board

Returns

The board's serial number

function getTime

(top)

Call type:

function getTime()

Description

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

Returns

See description above

Examples

This function is used in the following places in Espruino's documentation

variable global

(top)

Call type:

variable global

Description

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

Returns

The global scope

variable HIGH

(top)

Call type:

variable HIGH

Returns

Logic 1 for Arduino compatibility - this is the same as just typing 1

variable Infinity

(top)

Call type:

variable Infinity

Returns

Positive Infinity (1/0)

function isNaN

(top)

Call type:

function isNaN(x)

Description

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

Parameters

x -

Returns

True is the value is NaN, false if not.

function load

(top)

Call type:

function load()

Description

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.

variable LOW

(top)

Call type:

variable LOW

Returns

Logic 0 for Arduino compatibility - this is the same as just typing 0

variable NaN

(top)

Call type:

variable NaN

Returns

Not a Number

function parseFloat

(top)

Call type:

function parseFloat(string)

Description

Convert a string representing a number into an float

Parameters

string -

Returns

The value of the string

Examples

This function is used in the following places in Espruino's documentation

function parseInt

(top)

Call type:

function parseInt(string, radix)

Description

Convert a string representing a number into an integer

Parameters

string -

radix - The Radix of the string (optional)

Returns

The integer value of the string (or NaN)

Examples

This function is used in the following places in Espruino's documentation

function peek16

(top)

Call type:

function peek16(addr, count)

Description

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

Parameters

addr - The address in memory to read

count - (optional) the number of items to read. If >1 a Uint16Array will be returned.

Returns

The value of memory at the given location

Examples

This function is used in the following places in Espruino's documentation

function peek32

(top)

Call type:

function peek32(addr, count)

Description

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

Parameters

addr - The address in memory to read

count - (optional) the number of items to read. If >1 a Uint32Array will be returned.

Returns

The value of memory at the given location

Examples

This function is used in the following places in Espruino's documentation

function peek8

(top)

Call type:

function peek8(addr, count)

Description

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

Parameters

addr - The address in memory to read

count - (optional) the number of items to read. If >1 a Uint8Array will be returned.

Returns

The value of memory at the given location

function pinMode

(top)

Call type:

function pinMode(pin, mode, automatic)

Description

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

Parameters

pin - The pin to set pin mode for

mode - The mode - a string that is either 'analog', 'input', 'input_pullup', 'input_pulldown', 'output', 'opendrain', 'af_output' or 'af_opendrain'. Do not include this argument or use 'auto' if you want to revert to automatic pin mode setting.

automatic - Optional, default is false. If true, subsequent commands will automatically change the state (see notes below)

Examples

This function is used in the following places in Espruino's documentation

function poke16

(top)

Call type:

function poke16(addr, value)

Description

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

Parameters

addr - The address in memory to write

value - The value to write, or an array of values

Examples

This function is used in the following places in Espruino's documentation

function poke32

(top)

Call type:

function poke32(addr, value)

Description

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

Parameters

addr - The address in memory to write

value - The value to write, or an array of values

Examples

This function is used in the following places in Espruino's documentation

function poke8

(top)

Call type:

function poke8(addr, value)

Description

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

Parameters

addr - The address in memory to write

value - The value to write, or an array of values

function print

(top)

Call type:

function print(text, ...)

Description

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.

Parameters

text, ... -

Examples

This function is used in the following places in Espruino's documentation

function require

(top)

Call type:

function require(moduleName)

Description

Load the given module, and return the exported functions

Parameters

moduleName - A String containing the name of the given module

Returns

The result of evaluating the string

Examples

This function is used in the following places in Espruino's documentation

function reset

(top)

Call type:

function reset()

Description

Reset the interpreter - clear program memory, 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.

Examples

This function is used in the following places in Espruino's documentation

function save

(top)

Call type:

function save()

Description

Save program memory into flash. It will then be loaded automatically every time Espruino powers on or is hard-reset.

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

In order to stop the program saved with this command being loaded automatically, hold down Button 1 while also pressing reset. On some boards, Button 1 enters bootloader mode, so you will need to press Reset with Button 1 raised, and then hold Button 1 down a fraction of a second later.

function setBusyIndicator

(top)

Call type:

function setBusyIndicator(pin)

Description

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

Parameters

pin -

function setDeepSleep

(top)

Call type:

function setDeepSleep(sleep)

Description

Set whether we can enter deep sleep mode, which reduces power consumption to around 100uA. This only works on the Espruino Board.

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

Parameters

sleep -

Examples

This function is used in the following places in Espruino's documentation

function setInterval

(top)

Call type:

function setInterval(function, timeout, args, ...)

Description

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.

Parameters

function - A Function or String to be executed

timeout - The time between calls to the function

args, ... - Optional arguments to pass to the function when executed

Returns

An ID that can be passed to clearInterval

Examples

This function is used in the following places in Espruino's documentation

function setSleepIndicator

(top)

Call type:

function setSleepIndicator(pin)

Description

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.

Parameters

pin -

Examples

This function is used in the following places in Espruino's documentation

function setTime

(top)

Call type:

function setTime(time)

Description

Set the current system time in seconds (to the nearest second)

Parameters

time -

function setTimeout

(top)

Call type:

function setTimeout(function, timeout, args, ...)

Description

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.

Parameters

function - A Function or String to be executed

timeout - The time until the function will be executed

args, ... - Optional arguments to pass to the function when executed

Returns

An ID that can be passed to clearTimeout

Examples

This function is used in the following places in Espruino's documentation

function setWatch

(top)

Call type:

function setWatch(function, pin, options)

Description

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

The function may also take 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.

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, 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: The STM32 chip (used in the Espruino Board and Pico) cannot watch two pins with the same number - eg A0 and B0.

Parameters

function - A Function or String to be executed

pin - The pin to watch

options - If this is a boolean or integer, it determines whether to call this once (false = default) or every time a change occurs (true)
If this is an object, it can contain the following information: { repeat: true/false(default), edge:'rising'/'falling'/'both'(default), debounce:10}. debounce is the time in ms to wait for bounces to subside, or 0.

Returns

An ID that can be passed to clearWatch

Examples

This function is used in the following places in Espruino's documentation

function shiftOut

(top)

Call type:

function shiftOut(pins, options, data)

Description

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.

Parameters

pins - A pin, or an array of pins to use

options - Options, for instance the clock (see below)

data - The data to shift out

function show

(top)

Call type:

function show(image)

Description

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)

Parameters

image - The image to show

Examples

This function is used in the following places in Espruino's documentation

function trace

(top)

Call type:

function trace(root)

Description

Output debugging information Note: This is only available in some devices: not devices with low flash memory

Parameters

root - The symbol to output (optional). If nothing is specified, everything will be output

AES Class

(top)

Class containing AES encryption/decryption

Note: This library is currently only included in builds for the Espruino Pico and Espruino WiFi. For other boards you will have to make build your own firmware, and you may need to remove other features in order to make room.

Methods and Fields

AES.decrypt

(top)

Call type:

AES.decrypt(passphrase, key, options)

Parameters

passphrase - Message to decrypt

key - Key to encrypt message - must be an ArrayBuffer of 128, 192, or 256 BITS

options - An optional object, may specify { iv : new Uint8Array(16), mode : 'CBC|CFB|CTR|OFB|ECB' }

Returns

Returns an ArrayBuffer

AES.encrypt

(top)

Call type:

AES.encrypt(passphrase, key, options)

Parameters

passphrase - Message to encrypt

key - Key to encrypt message - must be an ArrayBuffer of 128, 192, or 256 BITS

options - An optional object, may specify { iv : new Uint8Array(16), mode : 'CBC|CFB|CTR|OFB|ECB' }

Returns

Returns an ArrayBuffer

Array Class

(top)

This is the built-in JavaScript class for arrays.

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

Methods and Fields

constructor Array

View MDN documentation

(top)

Call type:

new Array(args, ...)

Description

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

Parameters

args, ... - The length of the array OR any number of items to add to the array

Returns

An Array

function Array.concat

View MDN documentation

(top)

Call type:

function Array.concat(args, ...)

Description

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 only available in some devices: not devices with low flash memory

Parameters

args, ... - Any items to add to the array

Returns

An Array

function Array.every

View MDN documentation

(top)

Call type:

function Array.every(function, thisArg)

Description

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

Parameters

function - Function to be executed

thisArg - if specified, the function is called with 'this' set to thisArg (optional)

Returns

A boolean containing the result

function Array.fill

View MDN documentation

(top)

Call type:

function Array.fill(value, start, end)

Description

Fill this array with the given value, for every index >= start and < end Note: This is only available in some devices: not devices with low flash memory

Parameters

value - The value to fill the array with

start - Optional. The index to start from (or 0). If start is negative, it is treated as length+start where length is the length of the array

end - Optional. The index to end at (or the array length). If end is negative, it is treated as length+end.

Returns

This array

function Array.filter

View MDN documentation

(top)

Call type:

function Array.filter(function, thisArg)

Description

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

Parameters

function - Function to be executed

thisArg - if specified, the function is called with 'this' set to thisArg (optional)

Returns

An array containing the results

function Array.forEach

View MDN documentation

(top)

Call type:

function Array.forEach(function, thisArg)

Description

Executes a provided function once per array element.

Parameters

function - Function to be executed

thisArg - if specified, the function is called with 'this' set to thisArg (optional)

function Array.indexOf

View MDN documentation

(top)

Call type:

function Array.indexOf(value)

Description

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

Parameters

value - The value to check for

Returns

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

Array.isArray

View MDN documentation

(top)

Call type:

Array.isArray(var)

Description

Returns true if the provided object is an array

Parameters

var - The variable to be tested

Returns

True if var is an array, false if not.

function Array.join

View MDN documentation

(top)

Call type:

function Array.join(separator)

Description

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

Parameters

separator - The separator

Returns

A String representing the Joined array

property Array.length

View MDN documentation

(top)

Call type:

property Array.length

Description

Find the length of the array

Returns

The value of the array

function Array.map

View MDN documentation

(top)

Call type:

function Array.map(function, thisArg)

Description

Return an array which is made from the following: A.map(function) = [function(A[0]), function(A[1]), ...]

Parameters

function - Function used to map one item to another

thisArg - if specified, the function is called with 'this' set to thisArg (optional)

Returns

An array containing the results

function Array.pop

View MDN documentation

(top)

Call type:

function Array.pop()

Description

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.

Returns

The value that is popped off

function Array.push

View MDN documentation

(top)

Call type:

function Array.push(arguments, ...)

Description

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.

Parameters

arguments, ... - One or more arguments to add

Returns

The new size of the array

Examples

This function is used in the following places in Espruino's documentation

function Array.reduce

View MDN documentation

(top)

Call type:

function Array.reduce(callback, initialValue)

Description

Execute previousValue=initialValue and then previousValue = callback(previousValue, currentValue, index, array) for each element in the array, and finally return previousValue. Note: This is only available in some devices: not devices with low flash memory

Parameters

callback - Function used to reduce the array

initialValue - if specified, the initial value to pass to the function

Returns

The value returned by the last function called

function Array.reverse

View MDN documentation

(top)

Call type:

function Array.reverse()

Description

Reverse all elements in this array (in place) Note: This is only available in some devices: not devices with low flash memory

Returns

The array, but reversed.

function Array.shift

View MDN documentation

(top)

Call type:

function Array.shift()

Description

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 only available in some devices: not devices with low flash memory

Parameters

Returns

The element that was removed

function Array.slice

View MDN documentation

(top)

Call type:

function Array.slice(start, end)

Description

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

Parameters

start - Start index

end - End index (optional)

Returns

A new array

function Array.some

View MDN documentation

(top)

Call type:

function Array.some(function, thisArg)

Description

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

Parameters

function - Function to be executed

thisArg - if specified, the function is called with 'this' set to thisArg (optional)

Returns

A boolean containing the result

function Array.sort

View MDN documentation

(top)

Call type:

function Array.sort(var)

Description

Do an in-place quicksort of the array Note: This is only available in some devices: not devices with low flash memory

Parameters

var - A function to use to compare array elements (or undefined)

Returns

This array object

function Array.splice

View MDN documentation

(top)

Call type:

function Array.splice(index, howMany, elements, ...)

Description

Both remove and add items to an array

Parameters

index - Index at which to start changing the array. If negative, will begin that many elements from the end

howMany - An integer indicating the number of old array elements to remove. If howMany is 0, no elements are removed.

elements, ... - One or more items to add to the array

Returns

An array containing the removed elements. If only one element is removed, an array of one element is returned.

function Array.toString

View MDN documentation

(top)

Call type:

function Array.toString(radix)

Description

Convert the Array to a string

Parameters

radix - unused

Returns

A String representing the array

function Array.unshift

View MDN documentation

(top)

Call type:

function Array.unshift(elements, ...)

Description

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 only available in some devices: not devices with low flash memory

Parameters

elements, ... - One or more items to add to the beginning of the array

Returns

The new array length

ArrayBuffer Class

(top)

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

Methods and Fields

constructor ArrayBuffer

(top)

Call type:

new ArrayBuffer(byteLength)

Description

Create an Array Buffer object

Parameters

byteLength - The length in Bytes

Returns

An ArrayBuffer object

ArrayBufferView Class

(top)

This is the built-in JavaScript class that is the prototype for Uint8Array / Float32Array / etc

Methods and Fields

property ArrayBufferView.buffer

(top)

Call type:

property ArrayBufferView.buffer

Description

The buffer this view references

Returns

An ArrayBuffer object

property ArrayBufferView.byteLength

(top)

Call type:

property ArrayBufferView.byteLength

Description

The length, in bytes, of the view

Returns

The Length

property ArrayBufferView.byteOffset

(top)

Call type:

property ArrayBufferView.byteOffset

Description

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

Returns

The byte Offset

function ArrayBufferView.fill

(top)

Call type:

function ArrayBufferView.fill(value, start, end)

Description

Fill this array with the given value, for every index >= start and < end Note: This is only available in some devices: not devices with low flash memory

Parameters

value - The value to fill the array with

start - Optional. The index to start from (or 0). If start is negative, it is treated as length+start where length is the length of the array

end - Optional. The index to end at (or the array length). If end is negative, it is treated as length+end.

Returns

This array

Examples

This function is used in the following places in Espruino's documentation

function ArrayBufferView.forEach

(top)

Call type:

function ArrayBufferView.forEach(function, thisArg)

Description

Executes a provided function once per array element.

Parameters

function - Function to be executed

thisArg - if specified, the function is called with 'this' set to thisArg (optional)

function ArrayBufferView.indexOf

(top)

Call type:

function ArrayBufferView.indexOf(value)

Description

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

Parameters

value - The value to check for

Returns

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

function ArrayBufferView.join

(top)

Call type:

function ArrayBufferView.join(separator)

Description

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

Parameters

separator - The separator

Returns

A String representing the Joined array

function ArrayBufferView.map

(top)

Call type:

function ArrayBufferView.map(function, thisArg)

Description

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

Parameters

function - Function used to map one item to another

thisArg - if specified, the function is called with 'this' set to thisArg (optional)

Returns

An array containing the results

function ArrayBufferView.reduce

(top)

Call type:

function ArrayBufferView.reduce(callback, initialValue)

Description

Execute previousValue=initialValue and then previousValue = callback(previousValue, currentValue, index, array) for each element in the array, and finally return previousValue. Note: This is only available in some devices: not devices with low flash memory

Parameters

callback - Function used to reduce the array

initialValue - if specified, the initial value to pass to the function

Returns

The value returned by the last function called

function ArrayBufferView.reverse

(top)

Call type:

function ArrayBufferView.reverse()

Description

Reverse the contents of this arraybuffer in-place Note: This is only available in some devices: not devices with low flash memory

Returns

This array

function ArrayBufferView.set

(top)

Call type:

function ArrayBufferView.set(arr, offset)

Description

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

Parameters

arr - Floating point index to access

offset - The offset in this array at which to write the values (optional)

Examples

This function is used in the following places in Espruino's documentation

function ArrayBufferView.slice

(top)

Call type:

function ArrayBufferView.slice(start, end)

Description

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 only available in some devices: not devices with low flash memory

Parameters

start - Start index

end - End index (optional)

Returns

A new array

function ArrayBufferView.sort

(top)

Call type:

function ArrayBufferView.sort(var)

Description

Do an in-place quicksort of the array Note: This is only available in some devices: not devices with low flash memory

Parameters

var - A function to use to compare array elements (or undefined)

Returns

This array object

BluetoothDevice Class

(top)

Web Bluetooth-style device - get this using NRF.requestDevice(address)

Methods and Fields

property BluetoothDevice.gatt

(top)

Call type:

property BluetoothDevice.gatt

Description

Note: This is only available on some devices

Returns

A BluetoothRemoteGATTServer for this device

BluetoothRemoteGATTCharacteristic Class

(top)

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

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

Methods and Fields

function BluetoothRemoteGATTCharacteristic.readValue

(top)

Call type:

function BluetoothRemoteGATTCharacteristic.readValue()

Description

Read 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.readValue();
}).then(function(d) {
  console.log("Got:", JSON.stringify(d));
  device.disconnect();
}).catch(function() {
  console.log("Something's broken.");
});

Note: This is only available on some devices

Returns

A Promise that is resolved (or rejected) with data when the characteristic is read

function BluetoothRemoteGATTCharacteristic.startNotifications

(top)

Call type:

function BluetoothRemoteGATTCharacteristic.startNotifications()

Description

Starts notifications - whenever this characteristic's value changes, a characteristicvaluechanged event is fired.

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

Note: This is only available on some devices

Returns

A Promise that is resolved (or rejected) with data when notifications have been added

function BluetoothRemoteGATTCharacteristic.stopNotifications

(top)

Call type:

function BluetoothRemoteGATTCharacteristic.stopNotifications()

Description

Note: This is only available on some devices

Returns

A Promise that is resolved (or rejected) with data when notifications have been added

function BluetoothRemoteGATTCharacteristic.writeValue

(top)

Call type:

function BluetoothRemoteGATTCharacteristic.writeValue(data)

Description

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 on some devices

Parameters

data - The data to write

Returns

A Promise that is resolved (or rejected) when the characteristic is written

BluetoothRemoteGATTServer Class

(top)

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

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

Methods and Fields

function BluetoothRemoteGATTServer.connect

(top)

Call type:

function BluetoothRemoteGATTServer.connect()

Description

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

See NRF.requestDevice for usage examples.

Note: This is only available on some devices

Returns

A Promise that is resolved (or rejected) when the connection is complete

function BluetoothRemoteGATTServer.disconnect

(top)

Call type:

function BluetoothRemoteGATTServer.disconnect()

Description

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

Note: This is only available on some devices

function BluetoothRemoteGATTServer.getPrimaryService

(top)

Call type:

function BluetoothRemoteGATTServer.getPrimaryService(service)

Description

Note: This is only available on some devices

Parameters

service - The service UUID

Returns

A Promise that is resolved (or rejected) when the primary service is found

function BluetoothRemoteGATTServer.getPrimaryServices

(top)

Call type:

function BluetoothRemoteGATTServer.getPrimaryServices()

Description

Note: This is only available on some devices

Returns

A Promise that is resolved (or rejected) when the primary services are found

BluetoothRemoteGATTService Class

(top)

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

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

Methods and Fields

function BluetoothRemoteGATTService.getCharacteristic

(top)

Call type:

function BluetoothRemoteGATTService.getCharacteristic(characteristic)

Description

Note: This is only available on some devices

Parameters

characteristic - The characteristic UUID

Returns

A Promise that is resolved (or rejected) when the characteristic is found

function BluetoothRemoteGATTService.getCharacteristics

(top)

Call type:

function BluetoothRemoteGATTService.getCharacteristics()

Description

Note: This is only available on some devices

Returns

A Promise that is resolved (or rejected) when the characteristic is found

Boolean Class

(top)

Methods and Fields

constructor Boolean

View MDN documentation

(top)

Call type:

new Boolean(value)

Description

Creates a number

Parameters

value - A single value to be converted to a number

Returns

A Boolean object

CC3000 Library

(top)

Methods and Fields

CC3000.connect

(top)

Call type:

CC3000.connect(spi, cs, en, irq)

Description

Initialise the CC3000 and return a WLAN object

Parameters

spi - Device to use for SPI (or undefined to use the default). SPI should be 1,000,000 baud, and set to 'mode 1'

cs - The pin to use for Chip Select

en - The pin to use for Enable

irq - The pin to use for Interrupts

Returns

A WLAN Object

Examples

This function is used in the following places in Espruino's documentation

console Class

(top)

An Object that contains functions for writing to the interactive console

Methods and Fields

console.log

(top)

Call type:

console.log(text, ...)

Description

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.

Parameters

text, ... - One or more arguments to print

Examples

This function is used in the following places in Espruino's documentation

crypto Library

(top)

Cryptographic functions

Note: This library is currently only included in builds for the Espruino Pico and Espruino WiFi. For other boards you will have to make build your own firmware, and you may need to remove other features in order to make room.

Methods and Fields

crypto.AES

(top)

Call type:

crypto.AES

Description

Class containing AES encryption/decryption Note: This is only available in some devices: devices that support AES (Espruino Pico, Espruino WiFi or Linux)

Returns

See description above

crypto.PBKDF2

(top)

Call type:

crypto.PBKDF2(passphrase, salt, options)

Description

Password-Based Key Derivation Function 2 algorithm, using SHA512 Note: This is only available in some devices: devices with TLS and SSL support (Espruino Pico and Espruino WiFi only)

Parameters

passphrase - Passphrase

salt - Salt for turning passphrase into a key

options - Object of Options, { keySize: 8 (in 32 bit words), iterations: 10, hasher: 'SHA1'/'SHA224'/'SHA256'/'SHA384'/'SHA512' }

Returns

Returns an ArrayBuffer

crypto.SHA1

(top)

Call type:

crypto.SHA1(message)

Description

Performs a SHA1 hash and returns the result as a 20 byte ArrayBuffer Note: This is only available in some devices: devices that support Crypto Functionality (Espruino Pico, Espruino WiFi, Linux or ESP8266)

Parameters

message - The message to apply the hash to

Returns

Returns a 20 byte ArrayBuffer

crypto.SHA224

(top)

Call type:

crypto.SHA224(message)

Description

Performs a SHA224 hash and returns the result as a 28 byte ArrayBuffer Note: This is only available in some devices: devices that support Crypto Functionality (Espruino Pico, Espruino WiFi, Linux or ESP8266)

Parameters

message - The message to apply the hash to

Returns

Returns a 20 byte ArrayBuffer

crypto.SHA256

(top)

Call type:

crypto.SHA256(message)

Description

Performs a SHA256 hash and returns the result as a 32 byte ArrayBuffer Note: This is only available in some devices: devices that support Crypto Functionality (Espruino Pico, Espruino WiFi, Linux or ESP8266)

Parameters

message - The message to apply the hash to

Returns

Returns a 20 byte ArrayBuffer

crypto.SHA384

(top)

Call type:

crypto.SHA384(message)

Description

Performs a SHA384 hash and returns the result as a 48 byte ArrayBuffer Note: This is only available in some devices: devices that support Crypto Functionality (Espruino Pico, Espruino WiFi, Linux or ESP8266)

Parameters

message - The message to apply the hash to

Returns

Returns a 20 byte ArrayBuffer

crypto.SHA512

(top)

Call type:

crypto.SHA512(message)

Description

Performs a SHA512 hash and returns the result as a 64 byte ArrayBuffer Note: This is only available in some devices: devices that support Crypto Functionality (Espruino Pico, Espruino WiFi, Linux or ESP8266)

Parameters

message - The message to apply the hash to

Returns

Returns a 32 byte ArrayBuffer

Date Class

(top)

The built-in class for handling Dates

Methods and Fields

constructor Date

View MDN documentation

(top)

Call type:

new Date(args, ...)

Description

Creates a date object

Parameters

args, ... - Either nothing (current time), one numeric argument (milliseconds since 1970), a date string (see Date.parse), or [year, month, day, hour, minute, second, millisecond]

Returns

A Date object

Examples

This function is used in the following places in Espruino's documentation

function Date.getDate

View MDN documentation

(top)

Call type:

function Date.getDate()

Description

Day of the month 1..31

Returns

See description above

function Date.getDay

View MDN documentation

(top)

Call type:

function Date.getDay()

Description

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

Returns

See description above

function Date.getFullYear

View MDN documentation

(top)

Call type:

function Date.getFullYear()

Description

The year, eg. 2014

Returns

See description above

function Date.getHours

View MDN documentation

(top)

Call type:

function Date.getHours()

Description

0..23

Returns

See description above

function Date.getMilliseconds

View MDN documentation

(top)

Call type:

function Date.getMilliseconds()

Description

0..999

Returns

See description above

function Date.getMinutes

View MDN documentation

(top)

Call type:

function Date.getMinutes()

Description

0..59

Returns

See description above

function Date.getMonth

View MDN documentation

(top)

Call type:

function Date.getMonth()

Description

Month of the year 0..11

Returns

See description above

function Date.getSeconds

View MDN documentation

(top)

Call type:

function Date.getSeconds()

Description

0..59

Returns

See description above

function Date.getTime

View MDN documentation

(top)

Call type:

function Date.getTime()

Description

Return the number of milliseconds since 1970

Returns

See description above

function Date.getTimezoneOffset

View MDN documentation

(top)

Call type:

function Date.getTimezoneOffset()

Description

The getTimezoneOffset() method returns the time-zone offset from UTC, in minutes, for the current locale.

Returns

The difference, in minutes, between UTC and local time

Date.now

View MDN documentation

(top)

Call type:

Date.now()

Description

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

Returns

See description above

Date.parse

View MDN documentation

(top)

Call type:

Date.parse(str)

Description

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'

Parameters

str - A String

Returns

The number of milliseconds since 1970

Examples

This function is used in the following places in Espruino's documentation

function Date.toString

View MDN documentation

(top)

Call type:

function Date.toString()

Description

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

Note: This always assumes a timezone of GMT+0000

Returns

A String

function Date.toUTCString

View MDN documentation

(top)

Call type:

function Date.toUTCString()

Description

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

Note: This always assumes a timezone of GMT

Returns

A String

function Date.valueOf

View MDN documentation

(top)

Call type:

function Date.valueOf()

Description

Return the number of milliseconds since 1970

Returns

See description above

E Class

(top)

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

Methods and Fields

E.clip

(top)

Call type:

E.clip(x, min, max)

Description

Clip a number to be between min and max (inclusive) Note: This is only available in some devices: not devices with low flash memory

Parameters

x - A floating point value to clip

min - The smallest the value should be

max - The largest the value should be

Returns

The value of x, clipped so as not to be below min or above max.

Examples

This function is used in the following places in Espruino's documentation

E.connectSDCard

(top)

Call type:

E.connectSDCard(spi, csPin)

Description

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:

var spi = new SPI();
spi.setup({mosi:C7,miso:C8,sck:C9});
E.connectSDCard(spi,C6);
console.log(require("fs").readdirSync());
Note: This is only available in some devices: not devices with low flash memory

Parameters

spi - The SPI object to use for communication

csPin - The pin to use for Chip Select

Examples

This function is used in the following places in Espruino's documentation

E.convolve

(top)

Call type:

E.convolve(arr1, arr2, offset)

Description

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 only available in some devices: not devices with low flash memory

Parameters

arr1 - An array to convolve

arr2 - An array to convolve

offset - The mean value of the array

Returns

The variance of the given buffer

E.dumpLockedVars

(top)

Call type:

E.dumpLockedVars()

Description

Dump any locked variables that aren't referenced from global - for debugging memory leaks only. Note: This is only available in some devices: not release builds

E.dumpStr

(top)

Call type:

E.dumpStr()

Description

Get the current interpreter state in a text form such that it can be copied to a new device Note: This is only available in some devices: not devices with low flash memory

Returns

A String

E.dumpTimers

(top)

Call type:

E.dumpTimers()

Description

Output the current list of Utility Timer Tasks - for debugging only Note: This is only available in some devices: not release builds

E.enableWatchdog

(top)

Call type:

E.enableWatchdog(timeout, isAuto)

Description

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.

NOTE: This will not work with setDeepSleep unless you explicitly wake Espruino up with an interval of less than the timeout.

NOTE: This is only implemented on STM32 devices. Note: This is only available in some devices: not devices with low flash memory

Parameters

timeout - The timeout in seconds before a watchdog reset

isAuto - If undefined or true, the watchdog is kicked automatically. If not, you must call E.kickWatchdog() yourself

E.FFT

(top)

Call type:

E.FFT(arrReal, arrImage, inverse)

Description

Performs a Fast Fourier Transform (fft) 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). Note: This is only available in some devices: not devices with low flash memory

Parameters

arrReal - An array of real values

arrImage - An array of imaginary values (or if undefined, all values will be taken to be 0)

inverse - Set this to true if you want an inverse FFT - otherwise leave as 0

E.getAnalogVRef

(top)

Call type:

E.getAnalogVRef()

Description

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 only available in some devices: not devices with low flash memory

Returns

The voltage (in Volts) that a reading of 1 from analogRead actually represents - usually around 3.3v

Examples

This function is used in the following places in Espruino's documentation

E.getErrorFlags

(top)

Call type:

E.getErrorFlags()

Description

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. Note: This is only available in some devices: not devices with low flash memory

Returns

An array of error flags

E.getSizeOf

(top)

Call type:

E.getSizeOf(v, depth)

Description

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 only available in some devices: not devices with low flash memory

Parameters

v - A variable to get the size of

depth - The depth that detail should be provided for. If depth<=0 or undefined, a single integer will be returned

Returns

Information about the variable size - see below

E.getTemperature

(top)

Call type:

E.getTemperature()

Description

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.

Returns

The temperature in degrees C

Examples

This function is used in the following places in Espruino's documentation

E.HSBtoRGB

(top)

Call type:

E.HSBtoRGB(hue, sat, bri)

Description

Convert hue, saturation and brightness to red, green and blue (packed into an integer)

This replaces Graphics.setColorHSB and Graphics.setBgColorHSB. On devices with 24 bit colour it can be used as: Graphics.setColorHSB(E.HSBtoRGB(h, s, b)) Note: This is only available in some devices: not devices with low flash memory

Parameters

hue - The hue, as a value between 0 and 1

sat - The saturation, as a value between 0 and 1

bri - The brightness, as a value between 0 and 1

Returns

A 24 bit number containing bytes representing red, green, and blue: 0xBBGGRR

E.hwRand

(top)

Call type:

E.hwRand()

Description

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 only available in some devices: not devices with low flash memory

Returns

A random number

event E.init

(top)

Call type:

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

Description

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.

E.interpolate

(top)

Call type:

E.interpolate(array, index)

Description

Interpolate between two adjacent values in the Typed Array Note: This is only available in some devices: not devices with low flash memory

Parameters

array - A Typed Array to interpolate between

index - Floating point index to access

Returns

The result of interpolating between (int)index and (int)(index+1)

E.interpolate2d

(top)

Call type:

E.interpolate2d(array, width, x, y)

Description

Interpolate between four adjacent values in the Typed Array, in 2D. Note: This is only available in some devices: not devices with low flash memory

Parameters

array - A Typed Array to interpolate between

width - Integer 'width' of 2d array

x - Floating point X index to access

y - Floating point Y index to access

Returns

The result of interpolating in 2d between the 4 surrounding cells

E.kickWatchdog

(top)

Call type:

E.kickWatchdog()

Description

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

NOTE: This is only implemented on STM32 devices. Note: This is only available in some devices: not devices with low flash memory

E.lockConsole

(top)

Call type:

E.lockConsole()

Description

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

E.mapInPlace

(top)

Call type:

E.mapInPlace(from, to, map, bits)

Description

Take each element of the from array, look it up in map (or call the function with it as a first argument), and write it into the corresponding element in the to array. Note: This is only available in some devices: not devices with low flash memory

Parameters

from - An ArrayBuffer to read elements from

to - An ArrayBuffer to write elements too

map - An array or function to use to map one element to another

bits - If specified, the number of bits per element

E.memoryArea

(top)

Call type:

E.memoryArea(addr, len)

Description

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.

Parameters

addr - The address of the memory area

len - The length (in bytes) of the memory area

Returns

A Uint8Array

Examples

This function is used in the following places in Espruino's documentation

E.nativeCall

(top)

Call type:

E.nativeCall(addr, sig, data)

Description

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 only available in some devices: not devices with low flash memory

Parameters

addr - The address in memory of the function (or offset in data if it was supplied

sig - The signature of the call, returnType (arg1,arg2,...). Allowed types are void,bool,int,double,Pin,JsVar

data - (Optional) A string containing the function itself. If not supplied then 'addr' is used as an absolute address.

Returns

The native function

Examples

This function is used in the following places in Espruino's documentation

E.openFile

(top)

Call type:

E.openFile(path, mode)

Description

Open a file

Parameters

path - the path to the file to open.

mode - The mode to use when opening the file. Valid values for mode are 'r' for read, 'w' for write new, 'w+' for write existing, and 'a' for append. If not specified, the default is 'r'.

Returns

A File object

Examples

This function is used in the following places in Espruino's documentation

E.reverseByte

(top)

Call type:

E.reverseByte(x)

Description

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 only available in some devices: not devices with low flash memory

Parameters

x - A byte value to reverse the bits of

Returns

The byte with reversed bits

E.sendUSBHID

(top)

Call type:

E.sendUSBHID(data)

Parameters

data - An array of bytes to send as a USB HID packet

Returns

1 on success, 0 on failure

E.setBootCode

(top)

Call type:

E.setBootCode(code, alwaysExec)

Description

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

Parameters

code - The code to execute (as a string)

alwaysExec - Whether to always execute the code (even after a reset)

E.setClock

(top)

Call type:

E.setClock(options)

Description

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 only available in some devices: not devices with low flash memory

Parameters

options - Platform-specific options for setting clock speed

Returns

The actual frequency the clock has been set to

E.setPassword

(top)

Call type:

E.setPassword(opts)

Description

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.

Parameters

opts - The password - max 20 chars

E.setUSBHID

(top)

Call type:

E.setUSBHID(opts)

Description

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 some devices: devices that support USB HID (Espruino Pico and Espruino WiFi)

Parameters

opts - An object containing at least reportDescriptor, an array representing the report descriptor. Pass undefined to disable HID.

E.srand

(top)

Call type:

E.srand(v)

Description

Set the seed for the random number generator used by Math.random(). Note: This is only available in some devices: not devices with low flash memory

Parameters

v - The 32 bit integer seed to use for the random number generator

E.sum

(top)

Call type:

E.sum(arr)

Description

Sum the contents of the given Array, String or ArrayBuffer and return the result Note: This is only available in some devices: not devices with low flash memory

Parameters

arr - The array to sum

Returns

The sum of the given buffer

Examples

This function is used in the following places in Espruino's documentation

E.toArrayBuffer

(top)

Call type:

E.toArrayBuffer(str)

Description

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

Parameters

str - The string to convert to an ArrayBuffer

Returns

An ArrayBuffer that uses the given string

Examples

This function is used in the following places in Espruino's documentation

E.toString

(top)

Call type:

E.toString(args, ...)

Description

Returns a 'flat' string representing the data in the arguments.

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.

Parameters

args, ... - The arguments to convert to a String

Returns

A String

Examples

This function is used in the following places in Espruino's documentation

E.toUint8Array

(top)

Call type:

E.toUint8Array(args, ...)

Description

This creates a Uint8Array from the given arguments. If an argument is a String or an Array, each element is traversed and added as if it were an 8 bit value. If it is anything else, it is converted to an 8 bit value directly.

Parameters

args, ... - The arguments to convert to a Uint8Array

Returns

A Uint8Array

E.unmountSD

(top)

Call type:

E.unmountSD()

Description

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

E.variance

(top)

Call type:

E.variance(arr, mean)

Description

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 only available in some devices: not devices with low flash memory

Parameters

arr - The array to work out the variance for

mean - The mean value of the array

Returns

The variance of the given buffer

Error Class

(top)

The base class for runtime errors

Methods and Fields

constructor Error

View MDN documentation

(top)

Call type:

new Error(message)

Description

Creates an Error object

Parameters

message - An optional message string

Returns

An Error object

function Error.toString

View MDN documentation

(top)

Call type:

function Error.toString()

Returns

A String

ESP8266 Library

(top)

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.

Methods and Fields

ESP8266.crc32

(top)

Call type:

ESP8266.crc32(arrayOfData)

Parameters

arrayOfData - Array of data to CRC

Returns

32-bit CRC

ESP8266.deepSleep

(top)

Call type:

ESP8266.deepSleep(micros)

Description

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

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.

Parameters

micros - Number of microseconds to sleep.

ESP8266.dumpSocketInfo

(top)

Call type:

ESP8266.dumpSocketInfo()

Description

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

ESP8266.getFreeFlash

(top)

Call type:

ESP8266.getFreeFlash()

Description

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

Returns

Array of objects with addr and length properties describing the free flash areas available

ESP8266.getResetInfo

(top)

Call type:

ESP8266.getResetInfo()

Description

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 with the reset cause information

ESP8266.getState

(top)

Call type:

ESP8266.getState()

Description

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`

Returns

The state of the ESP8266

ESP8266.logDebug

(top)

Call type:

ESP8266.logDebug(enable)

Description

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

Parameters

enable - Enable or disable the debug logging.

ESP8266.neopixelWrite

(top)

Call type:

ESP8266.neopixelWrite(pin, arrayOfData)

Parameters

pin - Pin for output signal.

arrayOfData - Array of LED data.

ESP8266.ping

(top)

Call type:

ESP8266.ping(ipAddr, pingCallback)

Description

Perform a network ping request. The parameter can be either a String or a numeric IP address. Note: This function should probably be removed, or should it be part of the wifi library?

Parameters

ipAddr - A string representation of an IP address.

pingCallback - Optional callback function.

ESP8266.printLog

(top)

Call type:

ESP8266.printLog()

Description

Prints the contents of the debug log to the console.

ESP8266.readLog

(top)

Call type:

ESP8266.readLog()

Description

Returns one line from the log or up to 128 characters.

ESP8266.reboot

(top)

Call type:

ESP8266.reboot()

Description

Perform a hardware reset/reboot of the esp8266.

ESP8266.setCPUFreq

(top)

Call type:

ESP8266.setCPUFreq(freq)

Description

Note: This is deprecated. Use E.setClock(80/160) Note: Set the operating frequency of the ESP8266 processor. The default is 160Mhz.

Warning: changing the cpu frequency affects the timing of some I/O operations, notably of software SPI and I2C, so things may be a bit slower at 80Mhz.

Parameters

freq - Desired frequency - either 80 or 160.

ESP8266.setLog

(top)

Call type:

ESP8266.setLog(mode)

Description

Set the debug logging mode. It can be disabled (which frees ~1.2KB of heap), enabled in-memory only, or in-memory and output to a UART.

Parameters

mode - Debug log mode: 0=off, 1=in-memory only, 2=in-mem and uart0, 3=in-mem and uart1.

Ethernet Class

(top)

An instantiation of an Ethernet network adaptor

Methods and Fields

function Ethernet.getIP

(top)

Call type:

function Ethernet.getIP()

Description

Get the current IP address, subnet, gateway and mac address.

Returns

See description above

function Ethernet.setIP

(top)

Call type:

function Ethernet.setIP(options)

Description

Set the current IP address or get an IP from DHCP (if no options object is specified)

If 'mac' is specified as an option, it must be a string of the form "00:01:02:03:04:05"

Parameters

options - Object containing IP address options { ip : '1,2,3,4', subnet, gateway, dns, mac }, or do not supply an object in order to force DHCP.

Returns

True on success

File Class

(top)

This is the File object - it allows you to stream data to and from files (As opposed to the require('fs').readFile(..) style functions that read an entire file).

To create a File object, you must type var fd = E.openFile('filepath','mode') - see E.openFile for more information.

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.

Methods and Fields

function File.close

(top)

Call type:

function File.close()

Description

Close an open file.

function File.pipe

(top)

Call type:

function File.pipe(destination, options)

Description

Pipe this file to a stream (an object with a 'write' method) Note: This is only available in some devices: not devices with low flash memory

Parameters

destination - The destination file/stream that will receive content from the source.

options - An optional object { chunkSize : int=32, end : bool=true, complete : function }
chunkSize : The amount of data to pipe from source to destination at a time
complete : a function to call when the pipe activity is complete
end : call the 'end' function on the destination when the source is finished

function File.read

(top)

Call type:

function File.read(length)

Description

Read data in a file in byte size chunks

Parameters

length - is an integer specifying the number of bytes to read.

Returns

A string containing the characters that were read

Examples

This function is used in the following places in Espruino's documentation

function File.seek

(top)

Call type:

function File.seek(nBytes)

Description

Seek to a certain position in the file

Parameters

nBytes - is an integer specifying the number of bytes to skip forwards.

function File.skip

(top)

Call type:

function File.skip(nBytes)

Description

Skip the specified number of bytes forward in the file

Parameters

nBytes - is a positive integer specifying the number of bytes to skip forwards.

function File.write

(top)

Call type:

function File.write(buffer)

Description

write data to a file

Parameters

buffer - A string containing the bytes to write

Returns

the number of bytes written

Examples

This function is used in the following places in Espruino's documentation

Flash Library

(top)

This module allows access to read and write the STM32's flash memory.

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 in your board's reference pages.

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

Methods and Fields

Flash.erasePage

(top)

Call type:

Flash.erasePage(addr)

Description

Erase a page of flash memory Note: This is only available in some devices: not devices with low flash memory

Parameters

addr - An address in the page that is to be erased

Flash.getFree

(top)

Call type:

Flash.getFree()

Description

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 only available in some devices: not devices with low flash memory

Returns

Array of objects with addr and length properties

Flash.getPage

(top)

Call type:

Flash.getPage(addr)

Description

Returns the start and length of the flash page containing the given address. Note: This is only available in some devices: not devices with low flash memory

Parameters

addr - An address in memory

Returns

An object of the form { addr : #, length : #}, where addr is the start address of the page, and length is the length of it (in bytes). Returns undefined if no page at address

Flash.read

(top)

Call type:

Flash.read(length, addr)

Description

Read flash memory from the given address Note: This is only available in some devices: not devices with low flash memory

Parameters

length - The amount of data to read (in bytes)

addr - The address to start reading from

Returns

A Uint8Array of data

Flash.write

(top)

Call type:

Flash.write(data, addr)

Description

Write data into memory at the given address - IN MULTIPLES OF 4 BYTES.

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 only available in some devices: not devices with low flash memory

Parameters

data - The data to write. This must be a multiple of 4 bytes.

addr - The address to start writing from, this must be on a word boundary (a multiple of 4)

Float32Array Class

(top)

This is the built-in JavaScript class for a typed array.

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

Methods and Fields

constructor Float32Array

(top)

Call type:

new Float32Array(arr, byteOffset, length)

Description

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 ArrayBuffer view (eg. Uint8Array rather than ArrayBuffer) is given, it will be completely copied rather than referenced.

Parameters

arr - The array or typed array to base this off, or an integer which is the array length

byteOffset - The byte offset in the ArrayBuffer (ONLY IF the first argument was an ArrayBuffer)

length - The length (ONLY IF the first argument was an ArrayBuffer)

Returns

A typed array

Float64Array Class

(top)

This is the built-in JavaScript class for a typed array.

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

Methods and Fields

constructor Float64Array

(top)

Call type:

new Float64Array(arr, byteOffset, length)

Description

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 ArrayBuffer view (eg. Uint8Array rather than ArrayBuffer) is given, it will be completely copied rather than referenced.

Parameters

arr - The array or typed array to base this off, or an integer which is the array length

byteOffset - The byte offset in the ArrayBuffer (ONLY IF the first argument was an ArrayBuffer)

length - The length (ONLY IF the first argument was an ArrayBuffer)

Returns

A typed array

fs Library

(top)

This library handles interfacing with a FAT32 filesystem on an SD card. The API is designed to be similar to node.js's - However Espruino does not currently support asynchronous file IO, so the functions behave like node.js's xxxxSync functions. Versions of the functions with 'Sync' after them are also provided for compatibility.

Currently this provides minimal file IO - it's great for logging and loading/saving settings, but not good for loading large amounts of data as you will soon fill your memory up.

It is currently only available on boards that contain an SD card slot, such as the Olimexino and the HY. It can not currently be added to boards that did not ship with a card slot.

To use this, you must type var fs = require('fs') to get access to the library

Methods and Fields

fs.appendFile

(top)

Call type:

fs.appendFile(path, data)

Description

Append the data to the given file, created a new file if it doesn't exist

NOTE: Espruino does not yet support Async file IO, so this function behaves like the 'Sync' version.

Parameters

path - The path of the file to write

data - The data to write to the file

Returns

True on success, false on failure

fs.appendFileSync

(top)

Call type:

fs.appendFileSync(path, data)

Description

Append the data to the given file, created a new file if it doesn't exist Note: This is only available in some devices: not devices with low flash memory

Parameters

path - The path of the file to write

data - The data to write to the file

Returns

True on success, false on failure

Examples

This function is used in the following places in Espruino's documentation

fs.pipe

(top)

Call type:

fs.pipe(source, destination, options)

Parameters

source - The source file/stream that will send content.

destination - The destination file/stream that will receive content from the source.

options - An optional object { chunkSize : int=64, end : bool=true, complete : function }
chunkSize : The amount of data to pipe from source to destination at a time
complete : a function to call when the pipe activity is complete
end : call the 'end' function on the destination when the source is finished

fs.readdir

(top)

Call type:

fs.readdir(path)

Description

List all files in the supplied directory, returning them as an array of strings.

NOTE: Espruino does not yet support Async file IO, so this function behaves like the 'Sync' version.

Parameters

path - The path of the directory to list. If it is not supplied, '' is assumed, which will list the root directory

Returns

An array of filename strings (or undefined if the directory couldn't be listed)

Examples

This function is used in the following places in Espruino's documentation

fs.readdirSync

(top)

Call type:

fs.readdirSync(path)

Description

List all files in the supplied directory, returning them as an array of strings. Note: This is only available in some devices: not devices with low flash memory

Parameters

path - The path of the directory to list. If it is not supplied, '' is assumed, which will list the root directory

Returns

An array of filename strings (or undefined if the directory couldn't be listed)

Examples

This function is used in the following places in Espruino's documentation

fs.readFile

(top)

Call type:

fs.readFile(path)

Description

Read all data from a file and return as a string

NOTE: Espruino does not yet support Async file IO, so this function behaves like the 'Sync' version.

Parameters

path - The path of the file to read

Returns

A string containing the contents of the file (or undefined if the file doesn't exist)

Examples

This function is used in the following places in Espruino's documentation

fs.readFileSync

(top)

Call type:

fs.readFileSync(path)

Description

Read all data from a file and return as a string.

Note: The size of files you can load using this method is limited by the amount of available RAM. To read files a bit at a time, see the File class. Note: This is only available in some devices: not devices with low flash memory

Parameters

path - The path of the file to read

Returns

A string containing the contents of the file (or undefined if the file doesn't exist)

Examples

This function is used in the following places in Espruino's documentation

fs.statSync

(top)

Call type:

fs.statSync(path)

Description

Return information on the given file. This returns an object with the following fields:

size: size in bytes dir: a boolean specifying if the file is a directory or not mtime: A Date structure specifying the time the file was last modified Note: This is only available in some devices: not devices with low flash memory

Parameters

path - The path of the file to get information on

Returns

An object describing the file, or undefined on failure

fs.unlink

(top)

Call type:

fs.unlink(path)

Description

Delete the given file

NOTE: Espruino does not yet support Async file IO, so this function behaves like the 'Sync' version. Note: This is only available in some devices: not devices with low flash memory

Parameters

path - The path of the file to delete

Returns

True on success, or false on failure

fs.unlinkSync

(top)

Call type:

fs.unlinkSync(path)

Description

Delete the given file Note: This is only available in some devices: not devices with low flash memory

Parameters

path - The path of the file to delete

Returns

True on success, or false on failure

fs.writeFile

(top)

Call type:

fs.writeFile(path, data)

Description

Write the data to the given file

NOTE: Espruino does not yet support Async file IO, so this function behaves like the 'Sync' version.

Parameters

path - The path of the file to write

data - The data to write to the file

Returns

True on success, false on failure

fs.writeFileSync

(top)

Call type:

fs.writeFileSync(path, data)

Description

Write the data to the given file Note: This is only available in some devices: not devices with low flash memory

Parameters

path - The path of the file to write

data - The data to write to the file

Returns

True on success, false on failure

Examples

This function is used in the following places in Espruino's documentation

Function Class

(top)

This is the built-in class for Functions

Methods and Fields

function Function.apply

View MDN documentation

(top)

Call type:

function Function.apply(this, args)

Description

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

Parameters

this - The value to use as the 'this' argument when executing the function

args - Optional Array of Arguments

Returns

The return value of executing this function

function Function.bind

(top)

Call type:

function Function.bind(this, params, ...)

Description

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

Parameters

this - The value to use as the 'this' argument when executing the function

params, ... - Optional Default parameters that are prepended to the call

Returns

The 'bound' function

Examples

This function is used in the following places in Espruino's documentation

function Function.call

View MDN documentation

(top)

Call type:

function Function.call(this, params, ...)

Description

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

Parameters

this - The value to use as the 'this' argument when executing the function

params, ... - Optional Parameters

Returns

The return value of executing this function

constructor Function

View MDN documentation

(top)

Call type:

new Function(args, ...)

Description

Creates a function

Parameters

args, ... - Zero or more arguments (as strings), followed by a string representing the code to run

Returns

A Number object

function Function.replaceWith

(top)

Call type:

function Function.replaceWith(newFunc)

Description

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.

Parameters

newFunc - The new function to replace this function with

Graphics Class

(top)

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 'LCD' object of type Graphics. For instance to draw a line you'd type: LCD.drawLine(0,0,100,100)

Methods and Fields

function Graphics.clear

(top)

Call type:

function Graphics.clear()

Description

Clear the LCD with the Background Color

Examples

This function is used in the following places in Espruino's documentation

Graphics.createArrayBuffer

(top)

Call type:

Graphics.createArrayBuffer(width, height, bpp, options)

Description

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

Parameters

width - Pixels wide

height - Pixels high

bpp - Number of bits per pixel

options - An object of other options. { zigzag : true/false(default), vertical_byte : true/false(default), msb : true/false(default), color_order: 'rgb'(default),'bgr',etc }
zigzag = whether to alternate the direction of scanlines for rows
vertical_byte = whether to align bits in a byte vertically or not
msb = when bits<8, store pixels msb first
color_order = re-orders the colour values that are supplied via setColor

Returns

The new Graphics object

Examples

This function is used in the following places in Espruino's documentation

Graphics.createCallback

(top)

Call type:

Graphics.createCallback(width, height, bpp, callback)

Description

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

Parameters

width - Pixels wide

height - Pixels high

bpp - Number of bits per pixel

callback - A function of the form function(x,y,col) that is called whenever a pixel needs to be drawn, or an object with: {setPixel:function(x,y,col),fillRect:function(x1,y1,x2,y2,col)}. All arguments are already bounds checked.

Returns

The new Graphics object

Examples

This function is used in the following places in Espruino's documentation

Graphics.createSDL

(top)

Call type:

Graphics.createSDL(width, height)

Description

Create a Graphics object that renders to SDL window (Linux-based devices only) Note: This is only available in some devices: Linux with SDL support compiled in

Parameters

width - Pixels wide

height - Pixels high

Returns

The new Graphics object

function Graphics.drawCircle

(top)

Call type:

function Graphics.drawCircle(x, y, rad)

Description

Draw an unfilled circle 1px wide in the Foreground Color

Parameters

x - The X axis

y - The Y axis

rad - The circle radius

function Graphics.drawImage

(top)

Call type:

function Graphics.drawImage(image, x, y)

Description

Draw an image at the specified position. If the image is 1 bit, the graphics foreground/background colours will be used. Otherwise color data will be copied as-is. Bitmaps are rendered MSB-first

Parameters

image - An object with the following fields { width : int, height : int, bpp : int, buffer : ArrayBuffer, transparent: optional int }. bpp = bits per pixel, transparent (if defined) is the colour that will be treated as transparent

x - The X offset to draw the image

y - The Y offset to draw the image

Examples

This function is used in the following places in Espruino's documentation

function Graphics.drawLine

(top)

Call type:

function Graphics.drawLine(x1, y1, x2, y2)

Description

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

Parameters

x1 - The left

y1 - The top

x2 - The right

y2 - The bottom

Examples

This function is used in the following places in Espruino's documentation

function Graphics.drawRect

(top)

Call type:

function Graphics.drawRect(x1, y1, x2, y2)

Description

Draw an unfilled rectangle 1px wide in the Foreground Color

Parameters

x1 - The left

y1 - The top

x2 - The right

y2 - The bottom

function Graphics.drawString

(top)

Call type:

function Graphics.drawString(str, x, y)

Description

Draw a string of text in the current font

Parameters

str - The string

x - The X position of the leftmost pixel

y - The Y position of the topmost pixel

function Graphics.fillCircle

(top)

Call type:

function Graphics.fillCircle(x, y, rad)

Description

Draw a filled circle in the Foreground Color

Parameters

x - The X axis

y - The Y axis

rad - The circle radius

function Graphics.fillPoly

(top)

Call type:

function Graphics.fillPoly(poly)

Description

Draw a filled polygon in the current foreground color

Parameters

poly - An array of vertices, of the form [x1,y1,x2,y2,x3,y3,etc]

function Graphics.fillRect

(top)

Call type:

function Graphics.fillRect(x1, y1, x2, y2)

Description

Fill a rectangular area in the Foreground Color

Parameters

x1 - The left

y1 - The top

x2 - The right

y2 - The bottom

function Graphics.getBgColor

(top)

Call type:

function Graphics.getBgColor()

Description

Get the background color to use for subsequent drawing operations

Returns

The integer value of the colour

function Graphics.getColor

(top)

Call type:

function Graphics.getColor()

Description

Get the color to use for subsequent drawing operations

Returns

The integer value of the colour

function Graphics.getHeight

(top)

Call type:

function Graphics.getHeight()

Description

The height of the LCD

Returns

The height of the LCD

function Graphics.getModified

(top)

Call type:

function Graphics.getModified(reset)

Description

Return the area of the Graphics canvas that has been modified, and optionally clear the modified area to 0.

For instance if g.setPixel(10,20) was called, this would return {x1:10, y1:20, x2:10, y2:20}

Parameters

reset - Whether to reset the modified area or not

Returns

An object {x1,y1,x2,y2} containing the modified area, or undefined if not modified

function Graphics.getPixel

(top)

Call type:

function Graphics.getPixel(x, y)

Description

Get a pixel's color

Parameters

x - The left

y - The top

Returns

The color

function Graphics.getWidth

(top)

Call type:

function Graphics.getWidth()

Description

The width of the LCD

Returns

The width of the LCD

function Graphics.lineTo

(top)

Call type:

function Graphics.lineTo(x, y)

Description

Draw a line from the last position of lineTo or moveTo to this position

Parameters

x - X value

y - Y value

function Graphics.moveTo

(top)

Call type:

function Graphics.moveTo(x, y)

Description

Move the cursor to a position - see lineTo

Parameters

x - X value

y - Y value

function Graphics.setBgColor

(top)

Call type:

function Graphics.setBgColor(r, g, b)

Description

Set the background color to use for subsequent drawing operations

Parameters

r - Red (between 0 and 1) OR an integer representing the color in the current bit depth and color order

g - Green (between 0 and 1)

b - Blue (between 0 and 1)

function Graphics.setColor

(top)

Call type:

function Graphics.setColor(r, g, b)

Description

Set the color to use for subsequent drawing operations

Parameters

r - Red (between 0 and 1) OR an integer representing the color in the current bit depth and color order

g - Green (between 0 and 1)

b - Blue (between 0 and 1)

Examples

This function is used in the following places in Espruino's documentation

function Graphics.setFontBitmap

(top)

Call type:

function Graphics.setFontBitmap()

Description

Make subsequent calls to drawString use the built-in 4x6 pixel bitmapped Font

function Graphics.setFontCustom

(top)

Call type:

function Graphics.setFontCustom(bitmap, firstChar, width, height)

Description

Make subsequent calls to drawString use a Custom Font of the given height. See the Fonts page for more information about custom fonts and how to create them.

Parameters

bitmap - A column-first, MSB-first, 1bpp bitmap containing the font bitmap

firstChar - The first character in the font - usually 32 (space)

width - The width of each character in the font. Either an integer, or a string where each character represents the width

height - The height as an integer

function Graphics.setFontVector

(top)

Call type:

function Graphics.setFontVector(size)

Description

Make subsequent calls to drawString use a Vector Font of the given height Note: This is only available in some devices: not devices with low flash memory

Parameters

size - The height of the font, as an integer

Examples

This function is used in the following places in Espruino's documentation

function Graphics.setPixel

(top)

Call type:

function Graphics.setPixel(x, y, col)

Description

Set a pixel's color

Parameters

x - The left

y - The top

col - The color

function Graphics.setRotation

(top)

Call type:

function Graphics.setRotation(rotation, reflect)

Description

Set the current rotation of the graphics device.

Parameters

rotation - The clockwise rotation. 0 for no rotation, 1 for 90 degrees, 2 for 180, 3 for 270

reflect - Whether to reflect the image

function Graphics.stringWidth

(top)

Call type:

function Graphics.stringWidth(str)

Description

Return the size in pixels of a string of text in the current font

Parameters

str - The string

Returns

The length of the string in pixels

HASH Class

(top)

Note: This class is currently only included in builds for the original Espruino boards. For other boards you will have to make build your own firmware.

Methods and Fields

function HASH.digest

(top)

Call type:

function HASH.digest(message)

Parameters

message - part of message

Returns

Hash digest

function HASH.hexdigest

(top)

Call type:

function HASH.hexdigest(message)

Parameters

message - part of message

Returns

Hash hexdigest

function HASH.update

(top)

Call type:

function HASH.update(message)

Parameters

message - part of message

hashlib Library

(top)

Note: This library is currently only included in builds for the original Espruino boards. For other boards you will have to make build your own firmware.

Methods and Fields

hashlib.sha224

(top)

Call type:

hashlib.sha224(message)

Parameters

message - message to hash

Returns

Returns a new HASH SHA224 Object

hashlib.sha256

(top)

Call type:

hashlib.sha256(message)

Parameters

message - message to hash

Returns

Returns a new HASH SHA256 Object

http Library

(top)

This library allows you to create http servers and make http requests

In order to use this, you will need an extra module to get network connectivity such as the TI CC3000 or WIZnet W5500.

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.

Methods and Fields

http.createServer

(top)

Call type:

http.createServer(callback)

Description

Create an HTTP Server

When a request to the server is made, the callback is called. In the callback you can use the methods on the response (httpSRs) to send data. You can also add request.on('data',function() { ... }) to listen for POSTed data

Parameters

callback - A function(request,response) that will be called when a connection is made

Returns

Returns a new httpSrv object

Examples

This function is used in the following places in Espruino's documentation

http.get

(top)

Call type:

http.get(options, callback)

Description

Request a webpage over HTTP - a convenience function for http.request() that makes sure the HTTP command is 'GET', and that calls end automatically.

require("http").get("http://pur3.co.uk/hello.txt", function(res) {
  res.on('data', function(data) {
    console.log("HTTP> "+data);
  });
  res.on('close', function(data) {
    console.log("Connection closed");
  });
});

See http.request() and the Internet page and ` for more usage examples.

Parameters

options - A simple URL, or an object containing host,port,path,method fields

callback - A function(res) that will be called when a connection is made. You can then call res.on('data', function(data) { ... }) and res.on('close', function() { ... }) to deal with the response.

Returns

Returns a new httpCRq object

Examples

This function is used in the following places in Espruino's documentation

http.request

(top)

Call type:

http.request(options, callback)

Description

Create an HTTP Request - end() must be called on it to complete the operation. options is of the form:

var options = {
    host: 'example.com', // host name
    port: 80,            // (optional) port, defaults to 80
    path: '/',           // path sent to server
    method: 'GET',       // HTTP command sent to server (must be uppercase 'GET', 'POST', etc)
    headers: { key : value, key : value } // (optional) HTTP headers
  };
require("http").request(options, function(res) {
  res.on('data', function(data) {
    console.log("HTTP> "+data);
  });
  res.on('close', function(data) {
    console.log("Connection closed");
  });
});

You can easily pre-populate options from a URL using var options = url.parse("http://www.example.com/foo.html")

Note: if TLS/HTTPS is enabled, options can have ca, key and cert fields. See tls.connect for more information about these and how to use them.

Parameters

options - An object containing host,port,path,method,headers fields (and also ca,key,cert if HTTPS is enabled)

callback - A function(res) that will be called when a connection is made. You can then call res.on('data', function(data) { ... }) and res.on('close', function() { ... }) to deal with the response.

Returns

Returns a new httpCRq object

Examples

This function is used in the following places in Espruino's documentation

httpCRq Class

(top)

The HTTP client request, returned by http.request() and http.get().

Methods and Fields

event httpCRq.drain

(top)

Call type:

httpCRq.on('drain', function() { ... });

Description

An event that is fired when the buffer is empty and it can accept more data to send.

function httpCRq.end

(top)

Call type:

function httpCRq.end(data)

Description

Finish this HTTP request - optional data to append as an argument

Parameters

data - A string containing data to send

event httpCRq.error

(top)

Call type:

httpCRq.on('error', function() { ... });

Description

An event that is fired if there is an error making the request and the response callback has not been invoked. In this case the error event concludes the request attempt. The error event function receives an error object as parameter with a code field and a message field.

function httpCRq.write

(top)

Call type:

function httpCRq.write(data)

Parameters

data - A string containing data to send

Returns

For note compatibility, the boolean false. When the send buffer is empty, a drain event will be sent

httpCRs Class

(top)

The HTTP client response, passed to the callback of http.request() an http.get().

Methods and Fields

function httpCRs.available

(top)

Call type:

function httpCRs.available()

Description

Return how many bytes are available to read. If there is a 'data' event handler, this will always return 0.

Returns

How many bytes are available

event httpCRs.close

(top)

Call type:

httpCRs.on('close', function() { ... });

Description

Called when the connection closes with one hadError boolean parameter, which indicates whether an error occurred.

event httpCRs.data

(top)

Call type:

httpCRs.on('data', function(data) { ... });

Description

The 'data' event is called when data is received. If a handler is defined with X.on('data', function(data) { ... }) then it will be called, otherwise data will be stored in an internal buffer, where it can be retrieved with X.read()

Parameters

data - A string containing one or more characters of received data

event httpCRs.error

(top)

Call type:

httpCRs.on('error', function() { ... });

Description

An event that is fired if there is an error receiving the response. The error event function receives an error object as parameter with a code field and a message field. After the error event the close even will also be triggered to conclude the HTTP request/response.

function httpCRs.pipe

(top)

Call type:

function httpCRs.pipe(destination, options)

Description

Pipe this to a stream (an object with a 'write' method) Note: This is only available in some devices: not devices with low flash memory

Parameters

destination - The destination file/stream that will receive content from the source.

options - An optional object { chunkSize : int=32, end : bool=true, complete : function }
chunkSize : The amount of data to pipe from source to destination at a time
complete : a function to call when the pipe activity is complete
end : call the 'end' function on the destination when the source is finished

function httpCRs.read

(top)

Call type:

function httpCRs.read(chars)

Description

Return a string containing characters that have been received

Parameters

chars - The number of characters to read, or undefined/0 for all available

Returns

A string containing the required bytes.

httpSRq Class

(top)

The HTTP server request

Methods and Fields

function httpSRq.available

(top)

Call type:

function httpSRq.available()

Description

Return how many bytes are available to read. If there is already a listener for data, this will always return 0.

Returns

How many bytes are available

event httpSRq.close

(top)

Call type:

httpSRq.on('close', function() { ... });

Description

Called when the connection closes.

event httpSRq.data

(top)

Call type:

httpSRq.on('data', function(data) { ... });

Description

The 'data' event is called when data is received. If a handler is defined with X.on('data', function(data) { ... }) then it will be called, otherwise data will be stored in an internal buffer, where it can be retrieved with X.read()

Parameters

data - A string containing one or more characters of received data

function httpSRq.pipe

(top)

Call type:

function httpSRq.pipe(destination, options)

Description

Pipe this to a stream (an object with a 'write' method) Note: This is only available in some devices: not devices with low flash memory

Parameters

destination - The destination file/stream that will receive content from the source.

options - An optional object { chunkSize : int=32, end : bool=true, complete : function }
chunkSize : The amount of data to pipe from source to destination at a time
complete : a function to call when the pipe activity is complete
end : call the 'end' function on the destination when the source is finished

function httpSRq.read

(top)

Call type:

function httpSRq.read(chars)

Description

Return a string containing characters that have been received

Parameters

chars - The number of characters to read, or undefined/0 for all available

Returns

A string containing the required bytes.

httpSRs Class

(top)

The HTTP server response

Methods and Fields

event httpSRs.close

(top)

Call type:

httpSRs.on('close', function() { ... });

Description

Called when the connection closes.

event httpSRs.drain

(top)

Call type:

httpSRs.on('drain', function() { ... });

Description

An event that is fired when the buffer is empty and it can accept more data to send.

function httpSRs.end

(top)

Call type:

function httpSRs.end(data)

Parameters

data - A string containing data to send

function httpSRs.write

(top)

Call type:

function httpSRs.write(data)

Parameters

data - A string containing data to send

Returns

For note compatibility, the boolean false. When the send buffer is empty, a drain event will be sent

function httpSRs.writeHead

(top)

Call type:

function httpSRs.writeHead(statusCode, headers)

Parameters

statusCode - The HTTP status code

headers - An object containing the headers

httpSrv Class

(top)

The HTTP server created by require('http').createServer

Methods and Fields

function httpSrv.close

(top)

Call type:

function httpSrv.close()

Description

Stop listening for new HTTP connections

function httpSrv.listen

(top)

Call type:

function httpSrv.listen(port)

Description

Start listening for new HTTP connections on the given port

Parameters

port - The port to listen on

I2C Class

(top)

This class allows use of the built-in I2C ports. Currently it allows I2C Master mode only.

All addresses are in 7 bit format. If you have an 8 bit address then you need to shift it one bit to the right.

Instances

  • I2C1 The first I2C port
  • I2C2 The second I2C port
  • I2C3 The third I2C port

Methods and Fields

I2C.find

(top)

Call type:

I2C.find(pin)

Description

Try and find an I2C hardware device that will work on this pin (eg. I2C1)

May return undefined if no device can be found.

Parameters

pin - A pin to search with

Returns

An object of type I2C, or undefined if one couldn't be found.

constructor I2C

(top)

Call type:

new I2C()

Description

Create a software I2C port. This has limited functionality (no baud rate), but it can work on any pins.

Use SPI.setup to configure this port.

function I2C.readFrom

(top)

Call type:

function I2C.readFrom(address, quantity)

Description

Request bytes from the given slave device, and return them as a Uint8Array (packed array of bytes). This is like using Arduino Wire's requestFrom, available and read functions. Sends a STOP

Parameters

address - The 7 bit address of the device to request bytes from, or an object of the form {address:12, stop:false} to send this data without a STOP signal.

quantity - The number of bytes to request

Returns

The data that was returned - as a Uint8Array

function I2C.setup

(top)

Call type:

function I2C.setup(options)

Description

Set up this I2C port

If not specified in options, the default pins are used (usually the lowest numbered pins on the lowest port that supports this peripheral)

Parameters

options - An optional structure containing extra information on initialising the I2C port
{scl:pin, sda:pin, bitrate:100000}
You can find out which pins to use by looking at your board's reference page and searching for pins with the I2C marker. Note that 400000kHz is the maximum bitrate for most parts.

Examples

This function is used in the following places in Espruino's documentation

function I2C.writeTo

(top)

Call type:

function I2C.writeTo(address, data, ...)

Description

Transmit to the slave device with the given address. This is like Arduino's beginTransmission, write, and endTransmission rolled up into one.

Parameters

address - The 7 bit address of the device to transmit to, or an object of the form {address:12, stop:false} to send this data without a STOP signal.

data, ... - One or more items to write. May be ints, strings, arrays, or objects of the form {data: ..., count:#}.

Int16Array Class

(top)

This is the built-in JavaScript class for a typed array.

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

Methods and Fields

constructor Int16Array

(top)

Call type:

new Int16Array(arr, byteOffset, length)

Description

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 ArrayBuffer view (eg. Uint8Array rather than ArrayBuffer) is given, it will be completely copied rather than referenced.

Parameters

arr - The array or typed array to base this off, or an integer which is the array length

byteOffset - The byte offset in the ArrayBuffer (ONLY IF the first argument was an ArrayBuffer)

length - The length (ONLY IF the first argument was an ArrayBuffer)

Returns

A typed array

Int32Array Class

(top)

This is the built-in JavaScript class for a typed array.

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

Methods and Fields

constructor Int32Array

(top)

Call type:

new Int32Array(arr, byteOffset, length)

Description

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 ArrayBuffer view (eg. Uint8Array rather than ArrayBuffer) is given, it will be completely copied rather than referenced.

Parameters

arr - The array or typed array to base this off, or an integer which is the array length

byteOffset - The byte offset in the ArrayBuffer (ONLY IF the first argument was an ArrayBuffer)

length - The length (ONLY IF the first argument was an ArrayBuffer)

Returns

A typed array

Int8Array Class

(top)

This is the built-in JavaScript class for a typed array.

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

Methods and Fields

constructor Int8Array

(top)

Call type:

new Int8Array(arr, byteOffset, length)

Description

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 ArrayBuffer view (eg. Uint8Array rather than ArrayBuffer) is given, it will be completely copied rather than referenced.

Parameters

arr - The array or typed array to base this off, or an integer which is the array length

byteOffset - The byte offset in the ArrayBuffer (ONLY IF the first argument was an ArrayBuffer)

length - The length (ONLY IF the first argument was an ArrayBuffer)

Returns

A typed array

InternalError Class

(top)

The base class for internal errors

Methods and Fields

constructor InternalError

View MDN documentation

(top)

Call type:

new InternalError(message)

Description

Creates an InternalError object

Parameters

message - An optional message string

Returns

An InternalError object

function InternalError.toString

(top)

Call type:

function InternalError.toString()

Returns

A String

JSON Class

(top)

An Object that handles conversion to and from the JSON data interchange format

Methods and Fields

JSON.parse

View MDN documentation

(top)

Call type:

JSON.parse(string)

Description

Parse the given JSON string into a JavaScript object

NOTE: This implementation uses eval() internally, and as such it is unsafe as it can allow arbitrary JS commands to be executed.

Parameters

string - A JSON string

Returns

The JavaScript object created by parsing the data string

Examples

This function is used in the following places in Espruino's documentation

JSON.stringify

View MDN documentation

(top)

Call type:

JSON.stringify(data, replacer, space)

Description

Convert the given object into a JSON string which can subsequently be parsed with JSON.parse or eval.

Note: This differs from JavaScript's standard JSON.stringify in that:

  • The replacer argument is ignored
  • Typed arrays like new Uint8Array(5) will be dumped as if they were arrays, not as if they were objects (since it is more compact)

Parameters

data - The data to be converted to a JSON string

replacer - This value is ignored

space - The number of spaces to use for padding, a string, or null/undefined for no whitespace

Returns

A JSON string

Examples

This function is used in the following places in Espruino's documentation

Math Class

(top)

This is a standard JavaScript class that contains useful Maths routines

Methods and Fields

Math.abs

View MDN documentation

(top)

Call type:

Math.abs(x)

Parameters

x - A floating point value

Returns

The absolute value of x (eg, Math.abs(2)==2, but also Math.abs(-2)==2)

Examples

This function is used in the following places in Espruino's documentation

Math.acos

View MDN documentation

(top)

Call type:

Math.acos(x)

Parameters

x - The value to get the arc cosine of

Returns

The arc cosine of x, between 0 and PI

Math.asin

View MDN documentation

(top)

Call type:

Math.asin(x)

Parameters

x - The value to get the arc sine of

Returns

The arc sine of x, between -PI/2 and PI/2

Math.atan

View MDN documentation

(top)

Call type:

Math.atan(x)

Parameters

x - The value to get the arc tangent of

Returns

The arc tangent of x, between -PI/2 and PI/2

Math.atan2

View MDN documentation

(top)

Call type:

Math.atan2(y, x)

Parameters

y - The Y-part of the angle to get the arc tangent of

x - The X-part of the angle to get the arc tangent of

Returns

The arctangent of Y/X, between -PI and PI

Math.ceil

View MDN documentation

(top)

Call type:

Math.ceil(x)

Parameters

x - The value to round up

Returns

x, rounded upwards to the nearest integer

Math.clip

(top)

Call type:

Math.clip(x, min, max)

Description

DEPRECATED - Please use E.clip() instead. Clip a number to be between min and max (inclusive) Note: This is only available in some devices: not devices with low flash memory

Parameters

x - A floating point value to clip

min - The smallest the value should be

max - The largest the value should be

Returns

The value of x, clipped so as not to be below min or above max.

Math.cos

View MDN documentation

(top)

Call type:

Math.cos(theta)

Parameters

theta - The angle to get the cosine of

Returns

The cosine of theta

Examples

This function is used in the following places in Espruino's documentation

Math.E

View MDN documentation

(top)

Call type:

Math.E

Returns

The value of E - 2.718281828459045

Math.exp

View MDN documentation

(top)

Call type:

Math.exp(x)

Parameters

x - The value raise E to the power of

Returns

E^x

Math.floor

View MDN documentation

(top)

Call type:

Math.floor(x)

Parameters

x - The value to round down

Returns

x, rounded downwards to the nearest integer

Examples

This function is used in the following places in Espruino's documentation

Math.LN10

View MDN documentation

(top)

Call type:

Math.LN10

Returns

The natural logarithm of 10 - 2.302585092994046

Math.LN2

View MDN documentation

(top)

Call type:

Math.LN2

Returns

The natural logarithm of 2 - 0.6931471805599453

Math.log

View MDN documentation

(top)

Call type:

Math.log(x)

Parameters

x - The value to take the logarithm (base E) root of

Returns

The log (base E) of x

Examples

This function is used in the following places in Espruino's documentation

Math.LOG10E

View MDN documentation

(top)

Call type:

Math.LOG10E

Returns

The base 10 logarithm of e - 0.4342944819032518

Math.LOG2E

View MDN documentation

(top)

Call type:

Math.LOG2E

Returns

The base 2 logarithm of e - 1.4426950408889634

Math.max

View MDN documentation

(top)

Call type:

Math.max(args, ...)

Description

Find the maximum of a series of numbers

Parameters

args, ... - A floating point value to clip

Returns

The maximum of the supplied values

Examples

This function is used in the following places in Espruino's documentation

Math.min

View MDN documentation

(top)

Call type:

Math.min(args, ...)

Description

Find the minimum of a series of numbers

Parameters

args, ... - A floating point value to clip

Returns

The minimum of the supplied values

Examples

This function is used in the following places in Espruino's documentation

Math.PI

View MDN documentation

(top)

Call type:

Math.PI

Returns

The value of PI - 3.141592653589793

Math.pow

View MDN documentation

(top)

Call type:

Math.pow(x, y)

Parameters

x - The value to raise to the power

y - The power x should be raised to

Returns

x raised to the power y (x^y)

Math.random

View MDN documentation

(top)

Call type:

Math.random()

Returns

A random number between 0 and 1

Examples

This function is used in the following places in Espruino's documentation

Math.round

View MDN documentation

(top)

Call type:

Math.round(x)

Parameters

x - The value to round

Returns

x, rounded to the nearest integer

Examples

This function is used in the following places in Espruino's documentation

Math.sin

View MDN documentation

(top)

Call type:

Math.sin(theta)

Parameters

theta - The angle to get the sine of

Returns

The sine of theta

Examples

This function is used in the following places in Espruino's documentation

Math.sqrt

View MDN documentation

(top)

Call type:

Math.sqrt(x)

Parameters

x - The value to take the square root of

Returns

The square root of x

Math.SQRT1_2

View MDN documentation

(top)

Call type:

Math.SQRT1_2

Returns

The square root of 1/2 - 0.7071067811865476

Math.SQRT2

View MDN documentation

(top)

Call type:

Math.SQRT2

Returns

The square root of 2 - 1.4142135623730951

Math.tan

View MDN documentation

(top)

Call type:

Math.tan(theta)

Parameters

theta - The angle to get the tangent of

Returns

The tangent of theta

Math.wrap

(top)

Call type:

Math.wrap(x, max)

Description

Wrap a number around if it is less than 0 or greater than or equal to max. For instance you might do: Math.wrap(angleInDegrees, 360) Note: This is only available in some devices: not devices with low flash memory

Parameters

x - A floating point value to wrap

max - The largest the value should be

Returns

The value of x, wrapped so as not to be below min or above max.

Examples

This function is used in the following places in Espruino's documentation

Modules Class

(top)

Built-in class that caches the modules used by the require command

Methods and Fields

Modules.addCached

(top)

Call type:

Modules.addCached(id, sourcecode)

Description

Add the given module to the cache

Parameters

id - The module name to add

sourcecode - The module's sourcecode

Modules.getCached

(top)

Call type:

Modules.getCached()

Description

Return an array of module names that have been cached

Returns

An array of module names

Modules.removeAllCached

(top)

Call type:

Modules.removeAllCached()

Description

Remove all cached modules

Modules.removeCached

(top)

Call type:

Modules.removeCached(id)

Description

Remove the given module from the list of cached modules

Parameters

id - The module name to remove

net Library

(top)

This library allows you to create TCPIP 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.

Methods and Fields

net.connect

(top)

Call type:

net.connect(options, callback)

Description

Create a socket connection

Parameters

options - An object containing host,port fields

callback - A function(sckt) that will be called with the socket when a connection is made. You can then call sckt.write(...) to send data, and sckt.on('data', function(data) { ... }) and sckt.on('close', function() { ... }) to deal with the response.

Returns

Returns a new net.Socket object

Examples

This function is used in the following places in Espruino's documentation

net.createServer

(top)

Call type:

net.createServer(callback)

Description

Create a Server

When a request to the server is made, the callback is called. In the callback you can use the methods on the connection to send data. You can also add connection.on('data',function() { ... }) to listen for received data

Parameters

callback - A function(connection) that will be called when a connection is made

Returns

Returns a new Server Object

Examples

This function is used in the following places in Espruino's documentation

NetworkJS Library

(top)

Library that initialises a network device that calls into JavaScript

Methods and Fields

NetworkJS.create

(top)

Call type:

NetworkJS.create(obj)

Description

Initialise the network using the callbacks given and return the first argument. For instance:

require("NetworkJS").create({
  create : function(host,port) {
    // Create a socket and return its index, host is a string, port is an integer.
    // If host isn't defined, create a server socket
    console.log("Create",host,port);
    return 1;
  },
  close : function(sckt) {
    // Close the socket. returns nothing
  },
  accept : function(sckt) {
    // Accept the connection on the server socket. Returns socket number or -1 if no connection
    return -1;
  },
  recv : function(sckt, maxLen) {
    // Receive data. Returns a string (even if empty).
    // If non-string returned, socket is then closed
    return null;//or "";
  },
  send : function(sckt, data) {
    // Send data (as string). Returns the number of bytes sent - 0 is ok.
    // Less than 0
    return data.length;
  }
});

Parameters

obj - An object containing functions to access the network device

Returns

The object passed in

NodeMCU Class

(top)

This is a built-in class to allow you to use the ESP8266 NodeMCU boards's pin namings to access pins. It is only available on ESP8266-based boards.

Methods and Fields

NodeMCU.A0

(top)

Call type:

NodeMCU.A0

Returns

A Pin

NodeMCU.D0

(top)

Call type:

NodeMCU.D0

Returns

A Pin

NodeMCU.D1

(top)

Call type:

NodeMCU.D1

Returns

A Pin

NodeMCU.D10

(top)

Call type:

NodeMCU.D10

Returns

A Pin

NodeMCU.D2

(top)

Call type:

NodeMCU.D2

Returns

A Pin

NodeMCU.D3

(top)

Call type:

NodeMCU.D3

Returns

A Pin

NodeMCU.D4

(top)

Call type:

NodeMCU.D4

Returns

A Pin

NodeMCU.D5

(top)

Call type:

NodeMCU.D5

Returns

A Pin

NodeMCU.D6

(top)

Call type:

NodeMCU.D6

Returns

A Pin

NodeMCU.D7

(top)

Call type:

NodeMCU.D7

Returns

A Pin

NodeMCU.D8

(top)

Call type:

NodeMCU.D8

Returns

A Pin

NodeMCU.D9

(top)

Call type:

NodeMCU.D9

Returns

A Pin

NRF Class

(top)

The NRF class is for controlling functionality of the Nordic nRF51/nRF52 chips. Currently these only used in Puck.js and the BBC micro:bit.

The main part of this is control of Bluetooth Low Energy - both searching for devices, and changing advertising data.

Methods and Fields

event NRF.characteristicsDiscover

(top)

Call type:

NRF.on('characteristicsDiscover', function() { ... });

Description

Called with discovered characteristics when discovery is finished

event NRF.connect

(top)

Call type:

NRF.on('connect', function() { ... });

Description

Called when Espruino connects to another device - not when a a device connects to Espruino.

NRF.connect

(top)

Call type:

NRF.connect(mac)

Description

Connect to a BLE device by MAC address. Returns a promise, the argument of which is the BluetoothRemoteGATTServer connection.

NRF.connect("aa:bb:cc:dd:ee").then(function(server) {
  // ...
});

Note: This is only available on some devices

Parameters

mac - The MAC address to connect to

Returns

A Promise that is resolved (or rejected) when the connection is complete

event NRF.disconnect

(top)

Call type:

NRF.on('disconnect', function() { ... });

Description

Called when Espruino disconnects from another device - not when a a device disconnects from Espruino.

NRF.findDevices

(top)

Call type:

NRF.findDevices(callback, time)

Description

Utility function to return a list of BLE devices detected in range.

NRF.findDevices(function(devices) {
  console.log(devices);
}, 1000);

prints something like:

[
  BluetoothDevice {
    "id": "e7:e0:57:ad:36:a2 random",
    "rssi": -45,
    "services": [  ],
    "data": new ArrayBuffer([ ... ]),
    "name": "Puck.js 36a2"
   },
  BluetoothDevice {
    "id": "c0:52:3f:50:42:c9 random",
    "rssi": -65,
    "services": [  ],
    "data": new ArrayBuffer([ ... ]),
    "name": "Puck.js 8f57"
   }
 ]

You could then use BluetoothDevice.gatt.connect(...) on the device returned, to make a connection.

You can also use NRF.connect(...) on just the id string returned, which may be useful if you always want to connect to a specific device.

Parameters

callback - The callback to call with received advertising packets, or undefined to stop

time - The time in milliseconds to scan for (defaults to 2000)

Examples

This function is used in the following places in Espruino's documentation

NRF.getBattery

(top)

Call type:

NRF.getBattery()

Description

Get the battery level in volts

Returns

Battery level in volts

event NRF.NFCoff

(top)

Call type:

NRF.on('NFCoff', function() { ... });

Description

Called when an NFC field is no longer detected

event NRF.NFCon

(top)

Call type:

NRF.on('NFCon', function() { ... });

Description

Called when an NFC field is detected

NRF.nfcURL

(top)

Call type:

NRF.nfcURL(url)

Description

Enables NFC and starts advertising the given URL. For example:

NRF.nfcURL("http://espruino.com");

Note: This is only available on nRF52-based devices

Parameters

url - The URL string to expose on NFC, or undefined to disable NFC

Examples

This function is used in the following places in Espruino's documentation

NRF.requestDevice

(top)

Call type:

NRF.requestDevice(options)

Description

Search for available devices matching the given filters. Since we have no UI here, Espruino will pick the FIRST device it finds, or it'll call catch.

The following filter types are implemented:

  • services - list of services as strings (all of which must match). 128 bit services must be in the form '01230123-0123-0123-0123-012301230123'
  • name - exact device name
  • namePrefix - starting characters of device name

NRF.requestDevice({ filters: [{ namePrefix: 'Puck.js' }] }).then(function(device) { ... });
// or
NRF.requestDevice({ filters: [{ services: ['1823'] }] }).then(function(device) { ... });

You can also specify a timeout to wait for devices in milliseconds. The default is 2 seconds (2000):

NRF.requestDevice({ timeout:2000, filters: [ ... ] })

As a full example, to send data to another Puck.js to turn an LED on:

var gatt;
NRF.requestDevice({ filters: [{ namePrefix: 'Puck.js' }] }).then(function(device) {
  return device.gatt.connect();
}).then(function(g) {
  gatt = g;
  return gatt.getPrimaryService("6e400001-b5a3-f393-e0a9-e50e24dcca9e");
}).then(function(service) {
  return service.getCharacteristic("6e400002-b5a3-f393-e0a9-e50e24dcca9e");
}).then(function(characteristic) {
  characteristic.writeValue("LED1.set()\n");
}).then(function() {
  gatt.disconnect();
  console.log("Done!");
});

Or slightly more concisely, using ES6 arrow functions:

var gatt;
NRF.requestDevice({ filters: [{ namePrefix: 'Puck.js' }]}).then(
  device => device.gatt.connect()).then(
  g => (gatt=g).getPrimaryService("6e400001-b5a3-f393-e0a9-e50e24dcca9e")).then(
  service => service.getCharacteristic("6e400002-b5a3-f393-e0a9-e50e24dcca9e")).then(
  characteristic => characteristic.writeValue("LED1.reset()\n")).then(
  () => { gatt.disconnect(); console.log("Done!"); } );

Note that you'll have to keep track of the gatt variable so that you can disconnect the Bluetooth connection when you're done.

Note: This is only available on some devices

Parameters

options - Options used to filter the device to use

Returns

A Promise that is resolved (or rejected) when the connection is complete

Examples

This function is used in the following places in Espruino's documentation

NRF.sendHIDReport

(top)

Call type:

NRF.sendHIDReport(data, callback)

Description

Send a USB HID report. HID must first be enabled with NRF.setServices({}, {hid: hid_report})

Parameters

data - Input report data as an array

callback - A callback function to be called when the data is sent

Examples

This function is used in the following places in Espruino's documentation

event NRF.servicesDiscover

(top)

Call type:

NRF.on('servicesDiscover', function() { ... });

Description

Called with discovered services when discovery is finished

NRF.setAdvertising

(top)

Call type:

NRF.setAdvertising(data, options)

Description

Change the data that Espruino advertises.

Data can be of the form { UUID : data_as_byte_array }. The UUID should be a Bluetooth Service ID.

For example to return battery level at 95%, do:

NRF.setAdvertising({
  0x180F : [95]
});

Or you could report the current temperature:

setInterval(function() {
  NRF.setAdvertising({
    0x1809 : [Math.round(E.getTemperature())]
  });
}, 30000);

Note: Currently only standardised bluetooth UUIDs are allowed (see the list above).

You can also supply the raw advertising data in an array. For example to advertise as an Eddystone beacon:

NRF.setAdvertising([0x03,  // Length of Service List
  0x03,  // Param: Service List
  0xAA, 0xFE,  // Eddystone ID
  0x13,  // Length of Service Data
  0x16,  // Service Data
  0xAA, 0xFE, // Eddystone ID
  0x10,  // Frame type: URL
  0xF8, // Power
  0x03, // https://
  'g','o','o','.','g','l','/','B','3','J','0','O','c'],
    {interval:100});

options is an object, which can contain:

{
  name: "Hello" // The name of the device
  showName: true/false // include full name, or nothing
  discoverable: true/false // general discoverable, or limited - default is limited
  interval: 600 // Advertising interval in msec, between 20 and 10000
}

Parameters

data - The data to advertise as an object - see below for more info

options - An optional object of options

NRF.setRSSIHandler

(top)

Call type:

NRF.setRSSIHandler(callback)

Description

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

RSSI is the 'Received Signal Strength Indication' in dBm

``` // Start scanning NRF.setRSSIHandler(function(rssi) { console.log(rssi); }); // prints -85 (or similar)

// Stop Scanning NRF.setRSSIHandler(); ```

Parameters

callback - The callback to call with the RSSI value, or undefined to stop

NRF.setScan

(top)

Call type:

NRF.setScan(callback)

Description

Start/stop listening for BLE advertising packets within range. Returns a BluetoothDevice for each advertsing packet

// Start scanning
packets=10;
NRF.setScan(function(d) {
  packets--;
  console.log(d); // print packet info
  if (packets<=0)
    NRF.setScan(); // stop scanning
});

Note: BLE advertising packets can arrive quickly - faster than you'll be able to print them to the console. It's best only to print a few, or to use a function like NRF.findDevices(..) which will collate a list of available devices.

Parameters

callback - The callback to call with received advertising packets, or undefined to stop

NRF.setServices

(top)

Call type:

NRF.setServices(data, options)

Description

Change the services and characteristics Espruino advertises.

To expose some information on Characteristic ABCD on service BCDE you could do:

NRF.setServices({
  0xBCDE : {
    0xABCD : {
      value : "Hello",
      readable : true
    }
  }
});

Or to allow the 3 LEDs to be controlled by writing numbers 0 to 7 to a characteristic, you can do the following. evt.data is an array of bytes.

NRF.setServices({
  0xBCDE : {
    0xABCD : {
      writable : true,
      onWrite : function(evt) {
        digitalWrite([LED3,LED2,LED1], evt.data[0]);
      }
    }
  }
});

You can supply many different options:

NRF.setServices({
  0xBCDE : {
    0xABCD : {
      value : "Hello", // optional
      maxLen : 5, // optional (otherwise is length of initial value)
      broadcast : false, // optional, default is false
      readable : true,   // optional, default is false
      writable : true,   // optional, default is false
      notify : true,   // optional, default is false
      indicate : true,   // optional, default is false
      onWrite : function(evt) { // optional
        console.log("Got ", evt.data);
      }
    }
    // more characteristics allowed
  }
  // more services allowed
});

Note: UUIDs can be integers between 0 and 0xFFFF, strings of the form "ABCD", or strings of the form "ABCDABCD-ABCD-ABCD-ABCD-ABCDABCDABCD"

Note: Currently, services/characteristics can't be removed once added. As a result, calling setServices multiple times will cause characteristics to either be updated (value only) or ignored.

options can be of the form:

NRF.setServices(undefined, {
  hid : new Uint8Array(...), // optional, default is undefined. Enable BLE HID support
  uart : true, // optional, default is true. Enable BLE UART support
});

To enable BLE HID, you must set hid to an array which is the BLE report descriptor. The easiest way to do this is to use the ble_hid_controls or ble_hid_keyboard modules.

Parameters

data - The service (and characteristics) to advertise

options - Optional object containing options

Examples

This function is used in the following places in Espruino's documentation

NRF.setTxPower

(top)

Call type:

NRF.setTxPower(power)

Description

Set the BLE radio transmit power. The default TX power is 0 dBm.

Parameters

power - Transmit power. Accepted values are -40, -30, -20, -16, -12, -8, -4, 0, and 4 dBm. Others will give an error code.

NRF.sleep

(top)

Call type:

NRF.sleep()

Description

Disable Bluetooth communications

NRF.updateServices

(top)

Call type:

NRF.updateServices(data)

Description

Update values for the services and characteristics Espruino advertises. Only services and characteristics previously declared using setServices are affected.

To update the '0xABCD' characteristic in the '0xBCDE' service:

NRF.updateServices({
  0xBCDE : {
    0xABCD : {
      value : "World"
    }
  }
});

To notify connected clients of a change to the '0xABCD' characteristic in the '0xBCDE' service:

NRF.updateServices({
  0xBCDE : {
    0xABCD : {
      value : "World",
      notify: true
    }
  }
});
This only works if the characteristic was created with notify: true using setServices, otherwise the characteristic will be updated but no notification will be sent.

To indicate (i.e. notify with ACK) connected clients of a change to the '0xABCD' characteristic in the '0xBCDE' service:

NRF.updateServices({
  0xBCDE : {
    0xABCD : {
      value : "World",
      indicate: true
    }
  }
});
This only works if the characteristic was created with indicate: true using setServices, otherwise the characteristic will be updated but no notification will be sent.

Note: See setServices for more information

Parameters

data - The service (and characteristics) to update

NRF.wake

(top)

Call type:

NRF.wake()

Description

Enable Bluetooth communications (they are enabled by default)

Nucleo Class

(top)

This is the built-in class for the Arduino-style pin namings on ST Nucleo boards

Methods and Fields

Nucleo.A0

(top)

Call type:

Nucleo.A0

Returns

A Pin

Nucleo.A1

(top)

Call type:

Nucleo.A1

Returns

A Pin

Nucleo.A2

(top)

Call type:

Nucleo.A2

Returns

A Pin

Nucleo.A3

(top)

Call type:

Nucleo.A3

Returns

A Pin

Nucleo.A4

(top)

Call type:

Nucleo.A4

Returns

A Pin

Nucleo.A5

(top)

Call type:

Nucleo.A5

Returns

A Pin

Nucleo.D0

(top)

Call type:

Nucleo.D0

Returns

A Pin

Nucleo.D1

(top)

Call type:

Nucleo.D1

Returns

A Pin

Nucleo.D10

(top)

Call type:

Nucleo.D10

Returns

A Pin

Nucleo.D11

(top)

Call type:

Nucleo.D11

Returns

A Pin

Nucleo.D12

(top)

Call type:

Nucleo.D12

Returns

A Pin

Nucleo.D13

(top)

Call type:

Nucleo.D13

Returns

A Pin

Nucleo.D14

(top)

Call type:

Nucleo.D14

Returns

A Pin

Nucleo.D15

(top)

Call type:

Nucleo.D15

Returns

A Pin

Nucleo.D2

(top)

Call type:

Nucleo.D2

Returns

A Pin

Nucleo.D3

(top)

Call type:

Nucleo.D3

Returns

A Pin

Nucleo.D4

(top)

Call type:

Nucleo.D4

Returns

A Pin

Nucleo.D5

(top)

Call type:

Nucleo.D5

Returns

A Pin

Nucleo.D6

(top)

Call type:

Nucleo.D6

Returns

A Pin

Nucleo.D7

(top)

Call type:

Nucleo.D7

Returns

A Pin

Nucleo.D8

(top)

Call type:

Nucleo.D8

Returns

A Pin

Nucleo.D9

(top)

Call type:

Nucleo.D9

Returns

A Pin

Number Class

(top)

This is the built-in JavaScript class for numbers.

Methods and Fields

Number.MAX_VALUE

View MDN documentation

(top)

Call type:

Number.MAX_VALUE

Returns

Maximum representable value

Number.MIN_VALUE

View MDN documentation

(top)

Call type:

Number.MIN_VALUE

Returns

Smallest representable value

Number.NaN

View MDN documentation

(top)

Call type:

Number.NaN

Returns

Not a Number

Number.NEGATIVE_INFINITY

View MDN documentation

(top)

Call type:

Number.NEGATIVE_INFINITY

Returns

Negative Infinity (-1/0)

constructor Number

View MDN documentation

(top)

Call type:

new Number(value, ...)

Description

Creates a number

Parameters

value, ... - A single value to be converted to a number

Returns

A Number object

Number.POSITIVE_INFINITY

View MDN documentation

(top)

Call type:

Number.POSITIVE_INFINITY

Returns

Positive Infinity (1/0)

function Number.toFixed

View MDN documentation

(top)

Call type:

function Number.toFixed(decimalPlaces)

Description

Format the number as a fixed point number

Parameters

decimalPlaces - A number between 0 and 20 specifying the number of decimal digits after the decimal point

Returns

A string

Object Class

(top)

This is the built-in class for Objects

Methods and Fields

function Object.clone

(top)

Call type:

function Object.clone()

Description

Copy this object completely

Returns

A copy of this Object

Object.create

View MDN documentation

(top)

Call type:

Object.create(proto, propertiesObject)

Description

Creates a new object with the specified prototype object and properties. properties are currently unsupported.

Parameters

proto - A prototype object

propertiesObject - An object containing properties. NOT IMPLEMENTED

Returns

A new object

Object.defineProperties

View MDN documentation

(top)

Call type:

Object.defineProperties(obj, props)

Description

Adds new properties to the Object. See Object.defineProperty for more information

Parameters

obj - An object

props - An object whose fields represent property names, and whose values are property descriptors.

Returns

The object, obj.

Object.defineProperty

View MDN documentation

(top)

Call type:

Object.defineProperty(obj, name, desc)

Description

Add a new property to the Object. 'Desc' is an object with the following fields:

  • configurable (bool = false) - can this property be changed/deleted
  • enumerable (bool = false) - can this property be enumerated
  • value (anything) - the value of this property
  • writable (bool = false) - can the value be changed with the assignment operator?
  • get (function) - the getter function, or undefined if no getter
  • set (function) - the setter function, or undefined if no setter * Note: configurable, enumerable, writable, get, and set are not implemented and will be ignored.

Parameters

obj - An object

name - The name of the property

desc - The property descriptor

Returns

The object, obj.

function Object.emit

(top)

Call type:

function Object.emit(event, args, ...)

Description

Call the event listeners for this object, for instance http.emit('data', 'Foo'). See Node.js's EventEmitter.

Parameters

event - The name of the event, for instance 'data'

args, ... - Optional arguments

Object.getOwnPropertyDescriptor

View MDN documentation

(top)

Call type:

Object.getOwnPropertyDescriptor(obj, name)

Description

Get information on the given property in the object, or undefined

Parameters

obj - The object

name - The name of the property

Returns

An object with a description of the property. The values of writable/enumerable/configurable may not be entirely correct due to Espruino's implementation.

Object.getOwnPropertyNames

View MDN documentation

(top)

Call type:

Object.getOwnPropertyNames(object)

Description

Returns an array of all properties (enumerable or not) found directly on a given object.

Note: This doesn't currently work as it should for built-in objects and their prototypes. See bug #380

Parameters

object - The Object to return a list of property names for

Returns

An array of the Object's own properties

Object.getPrototypeOf

View MDN documentation

(top)

Call type:

Object.getPrototypeOf(object)

Description

Get the prototype of the given object - this is like writing object.__proto__ but is the 'proper' ES6 way of doing it

Parameters

object - An object

Returns

The prototype

function Object.hasOwnProperty

View MDN documentation

(top)

Call type:

function Object.hasOwnProperty(name)

Description

Return true if the object (not its prototype) has the given property.

NOTE: This currently returns false-positives for built-in functions in prototypes

Parameters

name - The name of the property to search for

Returns

True if it exists, false if it doesn't

Object.keys

View MDN documentation

(top)

Call type:

Object.keys(object)

Description

Return all enumerable keys of the given object

Parameters

object - The object to return keys for

Returns

An array of strings - one for each key on the given object

property Object.length

(top)

Call type:

property Object.length

Description

Find the length of the object

Returns

The length of the object

constructor Object

View MDN documentation

(top)

Call type:

new Object(value)

Description

Creates an Object from the supplied argument

Parameters

value - A single value to be converted to an object

Returns

An Object

function Object.on

(top)

Call type:

function Object.on(event, listener)

Description

Register an event listener for this object, for instance http.on('data', function(d) {...}). See Node.js's EventEmitter.

Parameters

event - The name of the event, for instance 'data'

listener - The listener to call when this event is received

Examples

This function is used in the following places in Espruino's documentation

function Object.removeAllListeners

(top)

Call type:

function Object.removeAllListeners(event)

Description

Removes all listeners, or those of the specified event.

Parameters

event - The name of the event, for instance 'data'

Examples

This function is used in the following places in Espruino's documentation

function Object.removeListener

(top)

Call type:

function Object.removeListener(event, listener)

Description

Removes the specified event listener.

function foo(d) {
  console.log(d);
}
Serial1.on("data", foo);
Serial1.removeListener("data", foo);

Parameters

event - The name of the event, for instance 'data'

listener - The listener to remove

Object.setPrototypeOf

View MDN documentation

(top)

Call type:

Object.setPrototypeOf(object, prototype)

Description

Set the prototype of the given object - this is like writing object.__proto__ = prototype but is the 'proper' ES6 way of doing it

Parameters

object - An object

prototype - The prototype to set on the object

Returns

The object passed in

function Object.toString

View MDN documentation

(top)

Call type:

function Object.toString(radix)

Description

Convert the Object to a string

Parameters

radix - If the object is an integer, the radix (between 2 and 36) to use. NOTE: Setting a radix does not work on floating point numbers.

Returns

A String representing the object

function Object.valueOf

View MDN documentation

(top)

Call type:

function Object.valueOf()

Description

Returns the primitive value of this object.

Returns

The primitive value of this object

OneWire Class

(top)

This class provides a software-defined OneWire master. It is designed to be similar to Arduino's OneWire library.

Methods and Fields

constructor OneWire

(top)

Call type:

new OneWire(pin)

Description

Create a software OneWire implementation on the given pin

Parameters

pin - The pin to implement OneWire on

Returns

A OneWire object

function OneWire.read

(top)

Call type:

function OneWire.read(count)

Description

Read a byte

Parameters

count - (optional) The amount of bytes to read

Returns

The byte that was read, or a Uint8Array if count was specified and >=0

function OneWire.reset

(top)

Call type:

function OneWire.reset()

Description

Perform a reset cycle

Returns

True is a device was present (it held the bus low)

function OneWire.search

(top)

Call type:

function OneWire.search()

Description

Search for devices

Returns

An array of devices that were found

Examples

This function is used in the following places in Espruino's documentation

function OneWire.search

(top)

Call type:

function OneWire.search(command)

Description

Search for devices

Parameters

command - (Optional) command byte. If not specified (or zero), this defaults to 0xF0. This can could be set to 0xEC to perform a DS18B20 'Alarm Search Command'

Returns

An array of devices that were found

Examples

This function is used in the following places in Espruino's documentation

function OneWire.select

(top)

Call type:

function OneWire.select(rom)

Description

Select a ROM - always performs a reset first

Parameters

rom - The device to select (get this using OneWire.search())

function OneWire.skip

(top)

Call type:

function OneWire.skip()

Description

Skip a ROM

function OneWire.write

(top)

Call type:

function OneWire.write(data, power)

Description

Write one or more bytes

Parameters

data - A byte (or array of bytes) to write

power - Whether to leave power on after write (default is false)

Pin Class

(top)

This is the built-in class for Pins, such as D0,D1,LED1, or BTN

You can call the methods on Pin, or you can use Wiring-style functions such as digitalWrite

Methods and Fields

function Pin.getInfo

(top)

Call type:

function Pin.getInfo()

Description

Get information about this pin and its capabilities. Of the form:

{
  "port"      : "A", // the Pin's port on the chip
  "num"       : 12, // the Pin's number
  "in_addr"   : 0x..., // (if available) the address of the pin's input address in bit-banded memory (can be used with peek)
  "out_addr"  : 0x..., // (if available) the address of the pin's output address in bit-banded memory (can be used with poke)
  "analog"    : { ADCs : [1], channel : 12 }, // If analog input is available
  "functions" : {
    "TIM1":{type:"CH1, af:0},
    "I2C3":{type:"SCL", af:1}
  }
}
Will return undefined if pin is not valid. Note: This is only available in some devices: not devices with low flash memory

Returns

An object containing information about this pins

function Pin.getMode

(top)

Call type:

function Pin.getMode()

Description

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

Returns

The pin mode, as a string

function Pin.mode

(top)

Call type:

function Pin.mode(mode)

Description

Set the mode of the given pin. See pinMode for more information on pin modes.

Parameters

mode - The mode - a string that is either 'analog', 'input', 'input_pullup', 'input_pulldown', 'output', 'opendrain', 'af_output' or 'af_opendrain'. Do not include this argument if you want to revert to automatic pin mode setting.

constructor Pin

(top)

Call type:

new Pin(value)

Description

Creates a pin from the given argument (or returns undefined if no argument)

Parameters

value - A value to be converted to a pin. Can be a number, pin, or String.

Returns

A Pin object

function Pin.read

(top)

Call type:

function Pin.read()

Description

Returns the input state of the pin as a boolean.

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

Returns

Whether pin is a logical 1 or 0

function Pin.reset

(top)

Call type:

function Pin.reset()

Description

Sets the output state of the pin to a 0

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

function Pin.set

(top)

Call type:

function Pin.set()

Description

Sets the output state of the pin to a 1

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

function Pin.write

(top)

Call type:

function Pin.write(value)

Description

Sets the output state of the pin to the parameter given

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

Parameters

value - Whether to set output high (true/1) or low (false/0)

function Pin.writeAtTime

(top)

Call type:

function Pin.writeAtTime(value, time)

Description

Sets the output state of the pin to the parameter given at the specified time.

Note: this doesn't change the mode of the pin to an output. To do that, you need to use pin.write(0) or pinMode(pin, 'output') first. Note: This is only available in some devices: not devices with low flash memory

Parameters

value - Whether to set output high (true/1) or low (false/0)

time - Time at which to write

process Class

(top)

This class contains information about Espruino itself

Methods and Fields

process.env

(top)

Call type:

process.env

Description

Returns an Object containing various pre-defined variables. standard ones are BOARD, VERSION

Returns

An object

process.memory

(top)

Call type:

process.memory()

Description

Run a Garbage Collection pass, and return an object containing information on memory usage.

  • free : Memory that is available to be used (in blocks)
  • usage : Memory that has been used (in blocks)
  • total : Total memory (in blocks)
  • history : Memory used for command history - that is freed if memory is low. Note that this is INCLUDED in the figure for 'free'
  • stackEndAddress : (on ARM) the address (that can be used with peek/poke/etc) of the END of the stack. The stack grows down, so unless you do a lot of recursion the bytes above this can be used.
  • flash_start : (on ARM) the address of the start of flash memory (usually 0x8000000)
  • flash_binary_end : (on ARM) the address in flash memory of the end of Espruino's firmware.
  • flash_code_start : (on ARM) the address in flash memory of pages that store any code that you save with save().
  • flash_length : (on ARM) the amount of flash memory this firmware was built for (in bytes). Note: Some STM32 chips actually have more memory than is advertised.

Memory units are specified in 'blocks', which are around 16 bytes each (depending on your device). See http://www.espruino.com/Performance for more information.

Note: To find free areas of flash memory, see require('Flash').getFree()

Returns

Information about memory usage

Examples

This function is used in the following places in Espruino's documentation

event process.uncaughtException

(top)

Call type:

process.on('uncaughtException', function() { ... });

Description

This event is called when an exception gets thrown and isn't caught (eg. it gets all the way back to the event loop).

You can use this for logging potential problems that might occur during execution.

process.version

(top)

Call type:

process.version

Description

Returns the version of Espruino as a String

Returns

The version of Espruino

Promise Class

(top)

This is the built-in class for ES6 Promises

Methods and Fields

Promise.all

View MDN documentation

(top)

Call type:

Promise.all(promises)

Description

Return a new promise that is resolved when all promises in the supplied array are resolved. Note: This is only available in some devices: not devices with low flash memory

Parameters

promises - An array of promises

Returns

A new Promise

function Promise.catch

View MDN documentation

(top)

Call type:

function Promise.catch(onRejected)

Parameters

onRejected - A callback that is called when this promise is rejected

Returns

The original Promise

constructor Promise

View MDN documentation

(top)

Call type:

new Promise(executor)

Description

Create a new Promise. The executor function is executed immediately (before the constructor even returns) and Note: This is only available in some devices: not devices with low flash memory

Parameters

executor - A function of the form function (resolve, reject)

Returns

A Promise

Promise.reject

View MDN documentation

(top)

Call type:

Promise.reject(promises)

Description

Return a new promise that is already rejected (at idle it'll call .catch) Note: This is only available in some devices: not devices with low flash memory

Parameters

promises - Data to pass to the .catch handler

Returns

A new Promise

Promise.resolve

View MDN documentation

(top)

Call type:

Promise.resolve(promises)

Description

Return a new promise that is already resolved (at idle it'll call .then) Note: This is only available in some devices: not devices with low flash memory

Parameters

promises - Data to pass to the .then handler

Returns

A new Promise

function Promise.then

View MDN documentation

(top)

Call type:

function Promise.then(onFulfilled, onRejected)

Parameters

onFulfilled - A callback that is called when this promise is resolved

onRejected - A callback that is called when this promise is rejected (or nothing)

Returns

The original Promise

Puck Class

(top)

Class containing Puck.js's utility functions.

Methods and Fields

Puck.capSense

(top)

Call type:

Puck.capSense(tx, rx)

Description

Capacitive sense. TX must be connected to RX pin and sense plate via 1MOhm resistor.

If no pins are supplied, the NFC ring is used for capacitive sense.

Parameters

tx -

rx -

Returns

Capacitive sense counter

Puck.getBatteryPercentage

(top)

Call type:

Puck.getBatteryPercentage()

Description

Return an approximate battery percentage remaining based on a normal CR2032 battery (2.8 - 2.0v)

Returns

A percentage between 0 and 100

Puck.IR

(top)

Call type:

Puck.IR(data)

Description

Transmit the given set of IR pulses - data should be an array of pulse times in milliseconds (as [on, off, on, off, on, etc]).

Parameters

data - An array of pulse lengths, in milliseconds

Examples

This function is used in the following places in Espruino's documentation

Puck.light

(top)

Call type:

Puck.light()

Description

Read a light value based on the light the red LED is seeing

Returns

A light value from 0 to 1

Puck.mag

(top)

Call type:

Puck.mag()

Description

Turn on the magnetometer, take a single reading, and then turn it off again.

An object of the form {x,y,z} is returned containing magnetometer readings. Due to residual magnetism in the Puck and magnetometer itself, with no magnetic field the Puck will not return {x:0,y:0,z:0}.

Instead, it's up to you to figure out what the 'zero value' is for your Puck in your location and to then subtract that from the value returned. If you're not trying to measure the Earth's magnetic field then it's a good idea to just take a reading at startup and use that.

With the aerial at the top of the board, the y reading is vertical, x is horizontal, and z is through the board.

Readings are in increments of 0.1 micro Tesla (uT). The Earth's magnetic field varies from around 25-60 uT, so the reading will vary by 250 to 600 depending on location.

Returns

An Object {x,y,z} of magnetometer readings as integers

event Puck.mag

(top)

Call type:

Puck.on('mag', function() { ... });

Description

Called after Puck.magOn() every time magnetometer data is discovered. There is one argument which is an object of the form

{x,y,z}' containing magnetometer readings
as integers (for more information see
Puck.mag()`.

Puck.magOff

(top)

Call type:

Puck.magOff()

Description

Turn the magnetometer off

Puck.magOn

(top)

Call type:

Puck.magOn(samplerate)

Description

Turn the magnetometer on and configure it. Samples will then cause a 'mag' event on 'Puck':

Puck.magOn();
Puck.on('mag', function(xyz) {
  console.log(xyz);
});
// Turn events off with Puck.magOff();

This call will be ignored if the magnetometer is already on.

If given an argument, the sample rate is set (if not, it's at 0.63Hz). The sample rate should be one of the following:

  • 80 Hz - 900uA
  • 40 Hz - 550uA
  • 20 Hz - 275uA
  • 10 Hz - 137uA
  • 5 Hz - 69uA
  • 2.5 Hz - 34uA
  • 1.25 Hz - 17uA
  • 0.63 Hz - 8uA
  • 0.31 Hz - 8uA
  • 0.16 Hz - 8uA
  • 0.08 Hz - 8uA

Parameters

samplerate - The Samplerate in Hz, or undefined

Examples

This function is used in the following places in Espruino's documentation

Puck.selfTest

(top)

Call type:

Puck.selfTest()

Description

Run a self-test, and return true for a pass. This checks for shorts between pins, so your Puck shouldn't have anything connected to it.

Note: This self-test auto starts if you hold the button on your Puck down while inserting the battery, leave it pressed for 3 seconds (while the green LED is lit) and release it soon after all LEDs turn on. 5 red blinks is a fail, 5 green is a pass.

Returns

True if the self-test passed

ReferenceError Class

(top)

The base class for reference errors - where a variable which doesn't exist has been accessed.

Methods and Fields

constructor ReferenceError

View MDN documentation

(top)

Call type:

new ReferenceError(message)

Description

Creates a ReferenceError object

Parameters

message - An optional message string

Returns

A ReferenceError object

function ReferenceError.toString

(top)

Call type:

function ReferenceError.toString()

Returns

A String

Serial Class

(top)

This class allows use of the built-in USARTs

Methods may be called on the USB, Serial1, Serial2, Serial3, Serial4, Serial5 and Serial6 objects. While different processors provide different numbers of USARTs, you can always rely on at least Serial1 and Serial2

Instances

  • Bluetooth The Bluetooth Serial port - used when data is sent or received over Bluetooth Smart on nRF51/nRF52 chips.
  • LoopbackA A loopback serial device. Data sent to LoopbackA comes out of LoopbackB and vice versa
  • LoopbackB A loopback serial device. Data sent to LoopbackA comes out of LoopbackB and vice versa
  • Serial1 The first Serial (USART) port
  • Serial2 The second Serial (USART) port
  • Serial3 The third Serial (USART) port
  • Serial4 The fourth Serial (USART) port
  • Serial5 The fifth Serial (USART) port
  • Serial6 The sixth Serial (USART) port
  • Telnet A telnet serial device that maps to the built-in telnet console server (devices that have built-in wifi only).
  • USB The USB Serial port

Methods and Fields

function Serial.available

(top)

Call type:

function Serial.available()

Description

Return how many bytes are available to read. If there is already a listener for data, this will always return 0.

Returns

How many bytes are available

event Serial.data

(top)

Call type:

Serial.on('data', function(data) { ... });

Description

The data event is called when data is received. If a handler is defined with X.on('data', function(data) { ... }) then it will be called, otherwise data will be stored in an internal buffer, where it can be retrieved with X.read()

Parameters

data - A string containing one or more characters of received data

Serial.find

(top)

Call type:

Serial.find(pin)

Description

Try and find a USART (Serial) hardware device that will work on this pin (eg. Serial1)

May return undefined if no device can be found.

Parameters

pin - A pin to search with

Returns

An object of type Serial, or undefined if one couldn't be found.

event Serial.framing

(top)

Call type:

Serial.on('framing', function() { ... });

Description

The framing event is called when there was activity on the input to the UART but the STOP bit wasn't in the correct place. This is either because there was noise on the line, or the line has been pulled to 0 for a long period of time.

Note: Even though there was an error, the byte will still be received and passed to the data handler.

function Serial.onData

(top)

Call type:

function Serial.onData(function)

Description

Serial.onData(func) has now been replaced with the event Serial.on(data, func)

Parameters

function -

event Serial.parity

(top)

Call type:

Serial.on('parity', function() { ... });

Description

The parity event is called when the UART was configured with a parity bit, and this doesn't match the bits that have actually been received.

Note: Even though there was an error, the byte will still be received and passed to the data handler.

function Serial.pipe

(top)

Call type:

function Serial.pipe(destination, options)

Description

Pipe this USART to a stream (an object with a 'write' method) Note: This is only available in some devices: not devices with low flash memory

Parameters

destination - The destination file/stream that will receive content from the source.

options - An optional object { chunkSize : int=32, end : bool=true, complete : function }
chunkSize : The amount of data to pipe from source to destination at a time
complete : a function to call when the pipe activity is complete
end : call the 'end' function on the destination when the source is finished

function Serial.print

(top)

Call type:

function Serial.print(string)

Description

Print a string to the serial port - without a line feed

Note: This function replaces any occurances of \n in the string with \r\n. To avoid this, use Serial.write.

Parameters

string - A String to print

Examples

This function is used in the following places in Espruino's documentation

function Serial.println

(top)

Call type:

function Serial.println(string)

Description

Print a line to the serial port with a newline (\r\n) at the end of it.

Note: This function converts data to a string first, eg Serial.print([1,2,3]) is equivalent to Serial.print("1,2,3"). If you'd like to write raw bytes, useSerial.write`.

Parameters

string - A String to print

Examples

This function is used in the following places in Espruino's documentation

function Serial.read

(top)

Call type:

function Serial.read(chars)

Description

Return a string containing characters that have been received

Parameters

chars - The number of characters to read, or undefined/0 for all available

Returns

A string containing the required bytes.

function Serial.setConsole

(top)

Call type:

function Serial.setConsole(force)

Description

Set this Serial port as the port for the JavaScript console (REPL).

Unless force is set to true, changes in the connection state of the board (for instance plugging in USB) will cause the console to change.

Parameters

force - Whether to force the console to this port

Examples

This function is used in the following places in Espruino's documentation

function Serial.setup

(top)

Call type:

function Serial.setup(baudrate, options)

Description

Setup this Serial port with the given baud rate and options.

If not specified in options, the default pins are used (usually the lowest numbered pins on the lowest port that supports this peripheral)

Parameters

baudrate - The baud rate - the default is 9600

options - An optional structure containing extra information on initialising the serial port.
{rx:pin,tx:pin,bytesize:8,parity:null/'none'/'o'/'odd'/'e'/'even',stopbits:1,flow:null/undefined/'none'/'xon',path:null/undefined/string}
You can find out which pins to use by looking at your board's reference page and searching for pins with the UART/USART markers.
Note that even after changing the RX and TX pins, if you have called setup before then the previous RX and TX pins will still be connected to the Serial port as well - until you set them to something else using digitalWrite

Examples

This function is used in the following places in Espruino's documentation

function Serial.write

(top)

Call type:

function Serial.write(data, ...)

Description

Write a character or array of data to the serial port

This method writes unmodified data, eg Serial.write([1,2,3]) is equivalent to Serial.write("\1\2\3"). If you'd like data converted to a string first, use Serial.print.

Parameters

data, ... - One or more items to write. May be ints, strings, arrays, or objects of the form {data: ..., count:#}.

Examples

This function is used in the following places in Espruino's documentation

Server Class

(top)

The socket server created by require('net').createServer

Methods and Fields

function Server.close

(top)

Call type:

function Server.close()

Description

Stop listening for new connections

function Server.listen

(top)

Call type:

function Server.listen(port)

Description

Start listening for new connections on the given port

Parameters

port - The port to listen on

Socket Class

(top)

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

Methods and Fields

function Socket.available

(top)

Call type:

function Socket.available()

Description

Return how many bytes are available to read. If there is already a listener for data, this will always return 0.

Returns

How many bytes are available

event Socket.close

(top)

Call type:

Socket.on('close', function(had_error) { ... });

Description

Called when the connection closes.

Parameters

had_error - A boolean indicating whether the connection had an error (use an error event handler to get error details).

event Socket.data

(top)

Call type:

Socket.on('data', function(data) { ... });

Description

The 'data' event is called when data is received. If a handler is defined with X.on('data', function(data) { ... }) then it will be called, otherwise data will be stored in an internal buffer, where it can be retrieved with X.read()

Parameters

data - A string containing one or more characters of received data

event Socket.drain

(top)

Call type:

Socket.on('drain', function() { ... });

Description

An event that is fired when the buffer is empty and it can accept more data to send.

function Socket.end

(top)

Call type:

function Socket.end(data)

Description

Close this socket - optional data to append as an argument

Parameters

data - A string containing data to send

event Socket.error

(top)

Call type:

Socket.on('error', function(details) { ... });

Description

There was an error on this socket and it is closing (or wasn't opened in the first place). If a "connected" event was issued on this socket then the error event is always followed by a close event. The error codes are:

  • -1: socket closed (this is not really an error and will not cause an error callback)
  • -2: out of memory (typically while allocating a buffer to hold data)
  • -3: timeout
  • -4: no route
  • -5: busy
  • -6: not found (DNS resolution)
  • -7: max sockets (... exceeded)
  • -8: unsent data (some data could not be sent)
  • -9: connection reset (or refused)
  • -10: unknown error
  • -11: no connection
  • -12: bad argument
  • -13: SSL handshake failed
  • -14: invalid SSL data

Parameters

details - An error object with an error code (a negative integer) and a message.

function Socket.pipe

(top)

Call type:

function Socket.pipe(destination, options)

Description

Pipe this to a stream (an object with a 'write' method) Note: This is only available in some devices: not devices with low flash memory

Parameters

destination - The destination file/stream that will receive content from the source.

options - An optional object { chunkSize : int=32, end : bool=true, complete : function }
chunkSize : The amount of data to pipe from source to destination at a time
complete : a function to call when the pipe activity is complete
end : call the 'end' function on the destination when the source is finished

function Socket.read

(top)

Call type:

function Socket.read(chars)

Description

Return a string containing characters that have been received

Parameters

chars - The number of characters to read, or undefined/0 for all available

Returns

A string containing the required bytes.

function Socket.write

(top)

Call type:

function Socket.write(data)

Parameters

data - A string containing data to send

Returns

For note compatibility, the boolean false. When the send buffer is empty, a drain event will be sent

SPI Class

(top)

This class allows use of the built-in SPI ports. Currently it is SPI master only.

Instances

  • SPI1 The first SPI port
  • SPI2 The second SPI port
  • SPI3 The third SPI port

Methods and Fields

SPI.find

(top)

Call type:

SPI.find(pin)

Description

Try and find an SPI hardware device that will work on this pin (eg. SPI1)

May return undefined if no device can be found.

Parameters

pin - A pin to search with

Returns

An object of type SPI, or undefined if one couldn't be found.

function SPI.send

(top)

Call type:

function SPI.send(data, nss_pin)

Description

Send data down SPI, and return the result. Sending an integer will return an integer, a String will return a String, and anything else will return a Uint8Array.

Sending multiple bytes in one call to send is preferable as they can then be transmitted end to end. Using multiple calls to send() will result in significantly slower transmission speeds.

For maximum speeds, please pass either Strings or Typed Arrays as arguments. Note that you can even pass arrays of arrays, like [1,[2,3,4],5]

Parameters

data - The data to send - either an Integer, Array, String, or Object of the form {data: ..., count:#}

nss_pin - An nSS pin - this will be lowered before SPI output and raised afterwards (optional). There will be a small delay between when this is lowered and when sending starts, and also between sending finishing and it being raised.

Returns

The data that was returned

Examples

This function is used in the following places in Espruino's documentation

function SPI.send4bit

(top)

Call type:

function SPI.send4bit(data, bit0, bit1, nss_pin)

Description

Send data down SPI, using 4 bits for each 'real' bit (MSB first). This can be useful for faking one-wire style protocols

Sending multiple bytes in one call to send is preferable as they can then be transmitted end to end. Using multiple calls to send() will result in significantly slower transmission speeds.

Parameters

data - The data to send - either an integer, array, or string

bit0 - The 4 bits to send for a 0 (MSB first)

bit1 - The 4 bits to send for a 1 (MSB first)

nss_pin - An nSS pin - this will be lowered before SPI output and raised afterwards (optional). There will be a small delay between when this is lowered and when sending starts, and also between sending finishing and it being raised.

Examples

This function is used in the following places in Espruino's documentation

function SPI.send8bit

(top)

Call type:

function SPI.send8bit(data, bit0, bit1, nss_pin)

Description

Send data down SPI, using 8 bits for each 'real' bit (MSB first). This can be useful for faking one-wire style protocols

Sending multiple bytes in one call to send is preferable as they can then be transmitted end to end. Using multiple calls to send() will result in significantly slower transmission speeds. Note: This is only available in some devices: not devices with low flash memory

Parameters

data - The data to send - either an integer, array, or string

bit0 - The 8 bits to send for a 0 (MSB first)

bit1 - The 8 bits to send for a 1 (MSB first)

nss_pin - An nSS pin - this will be lowered before SPI output and raised afterwards (optional). There will be a small delay between when this is lowered and when sending starts, and also between sending finishing and it being raised

function SPI.setup

(top)

Call type:

function SPI.setup(options)

Description

Set up this SPI port as an SPI Master.

Parameters

options - An optional structure containing extra information on initialising the SPI port
Please note that baud rate is set to the nearest that can be managed - which may be -+ 50%
{sck:pin, miso:pin, mosi:pin, baud:integer=100000, mode:integer=0, order:'msb'/'lsb'='msb' }
If sck,miso and mosi are left out, they will automatically be chosen. However if one or more is specified then the unspecified pins will not be set up.
You can find out which pins to use by looking at your board's reference page and searching for pins with the SPI marker.
The SPI mode is between 0 and 3 - see http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus#Clock_polarity_and_phase
On STM32F1-based parts, you cannot mix AF and non-AF pins (SPI pins are usually grouped on the chip - and you can't mix pins from two groups). Espruino will not warn you about this.

Examples

This function is used in the following places in Espruino's documentation

constructor SPI

(top)

Call type:

new SPI()

Description

Create a software SPI port. This has limited functionality (no baud rate), but it can work on any pins.

Use SPI.setup to configure this port.

function SPI.write

(top)

Call type:

function SPI.write(data, ...)

Description

Write a character or array of characters to SPI - without reading the result back.

For maximum speeds, please pass either Strings or Typed Arrays as arguments.

Parameters

data, ... - One or more items to write. May be ints, strings, arrays, or objects of the form {data: ..., count:#}.
If the last argument is a pin, it is taken to be the NSS pin

String Class

(top)

This is the built-in class for Text Strings.

Text Strings in Espruino are not zero-terminated, so you can store zeros in them.

Methods and Fields

function String.charAt

View MDN documentation

(top)

Call type:

function String.charAt(pos)

Description

Return a single character at the given position in the String.

Parameters

pos - The character number in the string. Negative values return characters from end of string (-1 = last char)

Returns

The character in the string

function String.charCodeAt

View MDN documentation

(top)

Call type:

function String.charCodeAt(pos)

Description

Return the integer value of a single character at the given position in the String.

Note that this returns 0 not 'NaN' for out of bounds characters

Parameters

pos - The character number in the string. Negative values return characters from end of string (-1 = last char)

Returns

The integer value of a character in the string

String.fromCharCode

View MDN documentation

(top)

Call type:

String.fromCharCode(code, ...)

Description

Return the character(s) represented by the given character code(s).

Parameters

code, ... - One or more character codes to create a string from (range 0-255).

Returns

The character

Examples

This function is used in the following places in Espruino's documentation

function String.indexOf

View MDN documentation

(top)

Call type:

function String.indexOf(substring, fromIndex)

Description

Return the index of substring in this string, or -1 if not found

Parameters

substring - The string to search for

fromIndex - Index to search from

Returns

The index of the string, or -1 if not found

Examples

This function is used in the following places in Espruino's documentation

function String.lastIndexOf

View MDN documentation

(top)

Call type:

function String.lastIndexOf(substring, fromIndex)

Description

Return the last index of substring in this string, or -1 if not found

Parameters

substring - The string to search for

fromIndex - Index to search from

Returns

The index of the string, or -1 if not found

property String.length

View MDN documentation

(top)

Call type:

property String.length

Description

Find the length of the string

Returns

The value of the string

function String.replace

View MDN documentation

(top)

Call type:

function String.replace(subStr, newSubStr)

Description

Search and replace ONE occurrance of subStr with newSubStr and return the result. This doesn't alter the original string. Regular expressions not supported.

Parameters

subStr - The string to search for

newSubStr - The string to replace it with

Returns

This string with subStr replaced

function String.slice

View MDN documentation

(top)

Call type:

function String.slice(start, end)

Parameters

start - The start character index, if negative it is from the end of the string

end - The end character index, if negative it is from the end of the string, and if omitted it is the end of the string

Returns

Part of this string from start for len characters

function String.split

View MDN documentation

(top)

Call type:

function String.split(separator)

Description

Return an array made by splitting this string up by the separator. eg. '1,2,3'.split(',')==[1,2,3]

Parameters

separator - The start character index

Returns

Part of this string from start for len characters

constructor String

View MDN documentation

(top)

Call type:

new String(str, ...)

Description

Create a new String

Parameters

str, ... - A value to turn into a string. If undefined or not supplied, an empty String is created.

Returns

A String

function String.substr

View MDN documentation

(top)

Call type:

function String.substr(start, len)

Parameters

start - The start character index

len - The number of characters

Returns

Part of this string from start for len characters

function String.substring

View MDN documentation

(top)

Call type:

function String.substring(start, end)

Parameters

start - The start character index

end - The end character index

Returns

The part of this string between start and end

function String.toLowerCase

View MDN documentation

(top)

Call type:

function String.toLowerCase()

Parameters

Returns

The lowercase version of this string

function String.toUpperCase

View MDN documentation

(top)

Call type:

function String.toUpperCase()

Parameters

Returns

The uppercase version of this string

function String.trim

View MDN documentation

(top)

Call type:

function String.trim()

Description

Return a new string with any whitespace (tabs, space, form feed, newline, carriage return, etc) removed from the beginning and end.

Returns

A String with Whitespace removed from the beginning and end

SyntaxError Class

(top)

The base class for syntax errors

Methods and Fields

constructor SyntaxError

View MDN documentation

(top)

Call type:

new SyntaxError(message)

Description

Creates a SyntaxError object

Parameters

message - An optional message string

Returns

A SyntaxError object

function SyntaxError.toString

(top)

Call type:

function SyntaxError.toString()

Returns

A String

TelnetServer Library

(top)

This library implements a telnet console for the Espruino interpreter. It requires a network connection, e.g. Wifi, and currently only functions on the ESP8266 and on Linux . It uses port 23 on the ESP8266 and port 2323 on Linux.

Note: To enable on Linux, run ./espruino --telnet

Methods and Fields

TelnetServer.setOptions

(top)

Call type:

TelnetServer.setOptions(options)

Parameters

options - Options controlling the telnet console server

tls Library

(top)

This library allows you to create TCPIP servers and clients using TLS encryption

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.

Methods and Fields

tls.connect

(top)

Call type:

tls.connect(options, callback)

Description

Create a socket connection using TLS

Options can have ca, key and cert fields, which should be the decoded content of the certificate.

var options = url.parse("localhost:1234");
options.key = atob("MIIJKQ ... OZs08C");
options.cert = atob("MIIFi ... Uf93rN+");
options.ca = atob("MIIFgDCC ... GosQML4sc=");
require("tls").connect(options, ... );

If you have the certificates as .pem files, you need to load these files, take the information between the lines beginning with ----, remove the newlines from it so you have raw base64, and then feed it into atob as above.

You can also: Just specify the filename (<=100 characters) and it will be loaded and parsed if you have an SD card connected. For instance options.key = "key.pem"; Specify a function, which will be called to retrieve the data. For instance `options.key = function() { eeprom.load_my_info(); };

For more information about generating and using certificates, see:

https://engineering.circle.com/https-authorized-certs-with-node-js/

(You'll need to use 2048 bit certificates as opposed to 4096 bit shown above) Note: This is only available in some devices: devices with TLS and SSL support (Espruino Pico and Espruino WiFi only)

Parameters

options - An object containing host,port fields

callback - A function(res) that will be called when a connection is made. You can then call res.on('data', function(data) { ... }) and res.on('close', function() { ... }) to deal with the response.

Returns

Returns a new net.Socket object

Examples

This function is used in the following places in Espruino's documentation

tv Library

(top)

This library provides TV out capability on the Espruino and Espruino Pico.

See the Television page for more information.

Methods and Fields

tv.setup

(top)

Call type:

tv.setup(options, width)

Description

This initialises the TV output. Options for PAL are as follows:

var g = require('tv').setup({ type : "pal",
  video : A7, // Pin - SPI MOSI Pin for Video output (MUST BE SPI1)
  sync : A6, // Pin - Timer pin to use for video sync
  width : 384,
  height : 270, // max 270
});

and for VGA:

var g = require('tv').setup({ type : "vga",
  video : A7, // Pin - SPI MOSI Pin for Video output (MUST BE SPI1)
  hsync : A6, // Pin - Timer pin to use for video sync
  vsync : A5, // Pin - pin to use for video sync
  width : 220,
  height : 240,
  repeat : 2, // amount of times to repeat each line
});

or

var g = require('tv').setup({ type : "vga",
  video : A7, // Pin - SPI MOSI Pin for Video output (MUST BE SPI1)
  hsync : A6, // Pin - Timer pin to use for video sync
  vsync : A5, // Pin - pin to use for video sync
  width : 220,
  height : 480,
  repeat : 1, // amount of times to repeat each line
});

See the Television page for more information.

Parameters

options - Various options for the TV output

width -

Returns

A graphics object

Examples

This function is used in the following places in Espruino's documentation

TypeError Class

(top)

The base class for type errors

Methods and Fields

function TypeError.toString

(top)

Call type:

function TypeError.toString()

Returns

A String

constructor TypeError

View MDN documentation

(top)

Call type:

new TypeError(message)

Description

Creates a TypeError object

Parameters

message - An optional message string

Returns

A TypeError object

Uint16Array Class

(top)

This is the built-in JavaScript class for a typed array.

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

Methods and Fields

constructor Uint16Array

(top)

Call type:

new Uint16Array(arr, byteOffset, length)

Description

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 ArrayBuffer view (eg. Uint8Array rather than ArrayBuffer) is given, it will be completely copied rather than referenced.

Parameters

arr - The array or typed array to base this off, or an integer which is the array length

byteOffset - The byte offset in the ArrayBuffer (ONLY IF the first argument was an ArrayBuffer)

length - The length (ONLY IF the first argument was an ArrayBuffer)

Returns

A typed array

Uint32Array Class

(top)

This is the built-in JavaScript class for a typed array.

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

Methods and Fields

constructor Uint32Array

(top)

Call type:

new Uint32Array(arr, byteOffset, length)

Description

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 ArrayBuffer view (eg. Uint8Array rather than ArrayBuffer) is given, it will be completely copied rather than referenced.

Parameters

arr - The array or typed array to base this off, or an integer which is the array length

byteOffset - The byte offset in the ArrayBuffer (ONLY IF the first argument was an ArrayBuffer)

length - The length (ONLY IF the first argument was an ArrayBuffer)

Returns

A typed array

Uint8Array Class

(top)

This is the built-in JavaScript class for a typed array.

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

Methods and Fields

constructor Uint8Array

(top)

Call type:

new Uint8Array(arr, byteOffset, length)

Description

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 ArrayBuffer view (eg. Uint8Array rather than ArrayBuffer) is given, it will be completely copied rather than referenced.

Parameters

arr - The array or typed array to base this off, or an integer which is the array length

byteOffset - The byte offset in the ArrayBuffer (ONLY IF the first argument was an ArrayBuffer)

length - The length (ONLY IF the first argument was an ArrayBuffer)

Returns

A typed array

Examples

This function is used in the following places in Espruino's documentation

Uint8ClampedArray Class

(top)

This is the built-in JavaScript class for a typed array.

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

Methods and Fields

constructor Uint8ClampedArray

View MDN documentation

(top)

Call type:

new Uint8ClampedArray(arr, byteOffset, length)

Description

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 ArrayBuffer view (eg. Uint8Array rather than ArrayBuffer) is given, it will be completely copied rather than referenced.

Clamped arrays clamp their values to the allowed range, rather than 'wrapping'. e.g. after a[0]=12345;, a[0]==255.

Parameters

arr - The array or typed array to base this off, or an integer which is the array length

byteOffset - The byte offset in the ArrayBuffer (ONLY IF the first argument was an ArrayBuffer)

length - The length (ONLY IF the first argument was an ArrayBuffer)

Returns

A typed array

url Class

(top)

This class helps to convert URLs into Objects of information ready for http.request/get

Methods and Fields

url.parse

(top)

Call type:

url.parse(urlStr, parseQuery)

Description

A utility function to split a URL into parts

This is useful in web servers for instance when handling a request.

For instance url.parse("/a?b=c&d=e",true) returns {"method":"GET","host":"","path":"/a?b=c&d=e","pathname":"/a","search":"?b=c&d=e","port":80,"query":{"b":"c","d":"e"}}

Parameters

urlStr - A URL to be parsed

parseQuery - Whether to parse the query string into an object not (default = false)

Returns

An object containing options for http.request or http.get. Contains method, host, path, pathname, search, port and query

Examples

This function is used in the following places in Espruino's documentation

Waveform Class

(top)

This class handles waveforms. In Espruino, a Waveform is a set of data that you want to input or output.

Methods and Fields

function Waveform.startInput

(top)

Call type:

function Waveform.startInput(output, freq, options)

Description

Will start inputting the waveform on the given pin that supports analog. If not repeating, it'll emit a finish event when it is done. Note: This is only available in some devices: not devices with low flash memory

Parameters

output - The pin to output on

freq - The frequency to output each sample at

options - Optional options struct {time:float,repeat:bool} where: time is the that the waveform with start output at, e.g. getTime()+1 (otherwise it is immediate), repeat is a