Version 1v84.58
function analogRead(pin)
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"
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.
The analog Value of the Pin between 0 and 1
This function is used in the following places in Espruino's documentation
function analogWrite(pin, value, options)
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"
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
This function is used in the following places in Espruino's documentation
variable arguments
A variable containing the arguments given to the function
An array containing all the arguments given to the function
function atob(binaryData)
Decode the supplied base64 string into a normal string
Note: This is only available in some devices: not devices with low flash memory
binaryData A string of base64 data to decode
A string containing the decoded data
This function is used in the following places in Espruino's documentation
function btoa(binaryData)
Encode the supplied string (or array) into a base64 string
Note: This is only available in some devices: not devices with low flash memory
binaryData A string of data to encode
A base64 encoded string
function changeInterval(id, time)
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 secondsThis 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.
id The id returned by a previous call to setInterval
time The new time period in ms
This function is used in the following places in Espruino's documentation
function clearInterval(id)
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
id The id returned by a previous call to setInterval
This function is used in the following places in Espruino's documentation
function clearTimeout(id)
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
id The id returned by a previous call to setTimeout
This function is used in the following places in Espruino's documentation
function clearWatch(id)
Clear the Watch that was created with setWatch. If no parameter is supplied, all watches will be removed.
id The id returned by a previous call to setWatch
This function is used in the following places in Espruino's documentation
function digitalPulse(pin, value, time)
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.
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')
This function is used in the following places in Espruino's documentation
function digitalRead(pin)
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
pin The pin to use
The digital Value of the Pin
This function is used in the following places in Espruino's documentation
function digitalWrite(pin, value)
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.
pin The pin to use
value Whether to pulse high (true) or low (false)
This function is used in the following places in Espruino's documentation
function dump()
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.
function echo(echoOn)
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.
echoOn
function edit(funcName)
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.
funcName The name of the function to edit (either a string or just the unquoted name)
This function is used in the following places in Espruino's documentation
function encodeURIComponent(str)
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
str A string to encode as a URI
A string containing the encoded data
function eval(code)
Evaluate a string containing JavaScript code
code
The result of evaluating the string
This function is used in the following places in Espruino's documentation
function getPinMode(pin)
Return the current mode of the given pin. See pinMode for more information.
Note: This is only available in some devices: not devices with low flash memory
pin The pin to check
The pin mode, as a string
function getSerial()
Get the serial number of this board
The board's serial number
function getTime()
Return the current system time in Seconds (as a floating point number)
See description above
This function is used in the following places in Espruino's documentation
variable global
A reference to the global scope, where everything is defined.
The global scope
variable HIGH
Logic 1 for Arduino compatibility - this is the same as just typing 1
variable Infinity
Positive Infinity (1/0)
function isNaN(x)
Whether the x is NaN (Not a Number) or not
x
True is the value is NaN, false if not.
function load()
Load program memory out of flash
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
Logic 0 for Arduino compatibility - this is the same as just typing 0
variable NaN
Not a Number
function parseFloat(string)
Convert a string representing a number into an float
string
The value of the string
This function is used in the following places in Espruino's documentation
function parseInt(string, radix)
Convert a string representing a number into an integer
string
radix The Radix of the string (optional)
The integer value of the string (or NaN)
This function is used in the following places in Espruino's documentation
function peek16(addr, count)
Read 16 bits of memory at the given location - DANGEROUS!
addr The address in memory to read
count (optional) the number of items to read. If >1 a Uint16Array will be returned.
The value of memory at the given location
This function is used in the following places in Espruino's documentation
function peek32(addr, count)
Read 32 bits of memory at the given location - DANGEROUS!
addr The address in memory to read
count (optional) the number of items to read. If >1 a Uint32Array will be returned.
The value of memory at the given location
This function is used in the following places in Espruino's documentation
function peek8(addr, count)
Read 8 bits of memory at the given location - DANGEROUS!
addr The address in memory to read
count (optional) the number of items to read. If >1 a Uint8Array will be returned.
The value of memory at the given location
function pinMode(pin, mode)
Set the mode of the given pin.
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
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)
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 if you want to revert to automatic pin mode setting.
This function is used in the following places in Espruino's documentation
function poke16(addr, value)
Write 16 bits of memory at the given location - VERY DANGEROUS!
addr The address in memory to write
value The value to write, or an array of values
This function is used in the following places in Espruino's documentation
function poke32(addr, value)
Write 32 bits of memory at the given location - VERY DANGEROUS!
addr The address in memory to write
value The value to write, or an array of values
This function is used in the following places in Espruino's documentation
function poke8(addr, value)
Write 8 bits of memory at the given location - VERY DANGEROUS!
addr The address in memory to write
value The value to write, or an array of values
function print(text, ...)
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.
text, ...
This function is used in the following places in Espruino's documentation
function require(moduleName)
Load the given module, and return the exported functions
moduleName A String containing the name of the given module
The result of evaluating the string
This function is used in the following places in Espruino's documentation
function reset()
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.
This function is used in the following places in Espruino's documentation
function save()
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(pin)
When Espruino is busy, set the pin specified here high. Set this to undefined to disable the feature.
pin
function setDeepSleep(sleep)
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.
sleep
This function is used in the following places in Espruino's documentation
function setInterval(function, timeout, args, ...)
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.
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
An ID that can be passed to clearInterval
This function is used in the following places in Espruino's documentation
function setSleepIndicator(pin)
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.
pin
This function is used in the following places in Espruino's documentation
function setTime(time)
Set the current system time in seconds (to the nearest second)
time
function setTimeout(function, timeout, args, ...)
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.
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
An ID that can be passed to clearTimeout
This function is used in the following places in Espruino's documentation
function setWatch(function, pin, options)
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.
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.
An ID that can be passed to clearWatch
This function is used in the following places in Espruino's documentation
function shiftOut(pins, options, data)
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.
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(image)
Show an image on the in-built 5x5 LED screen.
Image can be:
* A number where each bit represents a pixel (so 25 bits)
image The image to show
function trace(root)
Output debugging information
Note: This is only available in some devices: not devices with low flash memory
root The symbol to output (optional). If nothing is specified, everything will be output
Class containing AES encryption/decryption
Note: This library is currently only included in builds for the Espruino Pico. 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.
AES.decrypt(passphrase, key, options)
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 an ArrayBuffer
AES.encrypt(passphrase, key, options)
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 an ArrayBuffer
This is the built-in JavaScript class for arrays.
Arrays can be defined with
[],
new Array(), or
new Array(length)
new Array(args, ...)
Create an Array. Either give it one integer argument (>=0) which is the length of the array, or any number of arguments
args, ... The length of the array OR any number of items to add to the array
An Array
function Array.concat(args, ...)
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
args, ... Any items to add to the array
An Array
function Array.every(function, thisArg)
Return 'true' if the callback returns 'true' for every element in the array
function Function to be executed
thisArg if specified, the function is called with 'this' set to thisArg (optional)
A boolean containing the result
function Array.fill(value, start, end)
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
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.
This array
function Array.filter(function, thisArg)
Return an array which contains only those elements for which the callback function returns 'true'
function Function to be executed
thisArg if specified, the function is called with 'this' set to thisArg (optional)
An array containing the results
function Array.forEach(function, thisArg)
Executes a provided function once per array element.
function Function to be executed
thisArg if specified, the function is called with 'this' set to thisArg (optional)
function Array.indexOf(value)
Return the index of the value in the array, or -1
value The value to check for
the index of the value in the array, or -1
Array.isArray(var)
Returns true if the provided object is an array
var The variable to be tested
True if var is an array, false if not.
function Array.join(separator)
Join all elements of this array together into one string, using 'separator' between them. eg.
[1,2,3].join(' ')=='1 2 3'
separator The separator
A String representing the Joined array
property Array.length
Find the length of the array
The value of the array
function Array.map(function, thisArg)
Return an array which is made from the following:
A.map(function) = [function(A[0]), function(A[1]), ...]
function Function used to map one item to another
thisArg if specified, the function is called with 'this' set to thisArg (optional)
An array containing the results
function Array.pop()
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.
The value that is popped off
function Array.push(arguments, ...)
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.
arguments, ... One or more arguments to add
The new size of the array
This function is used in the following places in Espruino's documentation
function Array.reduce(callback, initialValue)
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
callback Function used to reduce the array
initialValue if specified, the initial value to pass to the function
The value returned by the last function called
function Array.reverse()
Reverse all elements in this array (in place)
Note: This is only available in some devices: not devices with low flash memory
The array, but reversed.
function Array.shift()
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
The element that was removed
function Array.slice(start, end)
Return a copy of a portion of this array (in a new array)
start Start index
end End index (optional)
A new array
function Array.some(function, thisArg)
Return 'true' if the callback returns 'true' for any of the elements in the array
function Function to be executed
thisArg if specified, the function is called with 'this' set to thisArg (optional)
A boolean containing the result
function Array.sort(var)
Do an in-place quicksort of the array
Note: This is only available in some devices: not devices with low flash memory
var A function to use to compare array elements (or undefined)
This array object
function Array.splice(index, howMany, elements, ...)
Both remove and add items to an array
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
An array containing the removed elements. If only one element is removed, an array of one element is returned.
function Array.toString(radix)
Convert the Array to a string
radix unused
A String representing the array
function Array.unshift(elements, ...)
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
elements, ... One or more items to add to the beginning of the array
The new array length
This is the built-in JavaScript class for array buffers.
new ArrayBuffer(byteLength)
Create an Array Buffer object
byteLength The length in Bytes
An ArrayBuffer object
This is the built-in JavaScript class that is the prototype for Uint8Array / Float32Array / etc
property ArrayBufferView.buffer
The buffer this view references
An ArrayBuffer object
property ArrayBufferView.byteLength
The length, in bytes, of the view
The Length
property ArrayBufferView.byteOffset
The offset, in bytes, to the first byte of the view within the ArrayBuffer
The byte Offset
function ArrayBufferView.fill(value, start, end)
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
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.
This array
This function is used in the following places in Espruino's documentation
function ArrayBufferView.forEach(function, thisArg)
Executes a provided function once per array element.
function Function to be executed
thisArg if specified, the function is called with 'this' set to thisArg (optional)
function ArrayBufferView.indexOf(value)
Return the index of the value in the array, or -1
value The value to check for
the index of the value in the array, or -1
function ArrayBufferView.join(separator)
Join all elements of this array together into one string, using 'separator' between them. eg.
[1,2,3].join(' ')=='1 2 3'
separator The separator
A String representing the Joined array
function ArrayBufferView.map(function, thisArg)
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
function Function used to map one item to another
thisArg if specified, the function is called with 'this' set to thisArg (optional)
An array containing the results
function ArrayBufferView.reduce(callback, initialValue)
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
callback Function used to reduce the array
initialValue if specified, the initial value to pass to the function
The value returned by the last function called
function ArrayBufferView.reverse()
Reverse the contents of this arraybuffer in-place
Note: This is only available in some devices: not devices with low flash memory
This array
function ArrayBufferView.set(arr, offset)
Copy the contents of array into this one, mapping this[x+offset]=array[x];
arr Floating point index to access
offset The offset in this array at which to write the values (optional)
This function is used in the following places in Espruino's documentation
function ArrayBufferView.slice(start, end)
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
start Start index
end End index (optional)
A new array
function ArrayBufferView.sort(var)
Do an in-place quicksort of the array
Note: This is only available in some devices: not devices with low flash memory
var A function to use to compare array elements (or undefined)
This array object
new Boolean(value)
Creates a number
value A single value to be converted to a number
A Boolean object
CC3000.connect(spi, cs, en, irq)
Initialise the CC3000 and return a WLAN object
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
A WLAN Object
This function is used in the following places in Espruino's documentation
An Object that contains functions for writing to the interactive console
console.log(text, ...)
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.
text, ... One or more arguments to print
This function is used in the following places in Espruino's documentation
Cryptographic functions
Note: This library is currently only included in builds for the Espruino Pico. 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.
crypto.AES
Class containing AES encryption/decryption
Note: This is only available in some devices: devices with TLS and SSL support (Espruino Pico only)
See description above
crypto.PBKDF2(passphrase, salt, options)
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 only)
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 an ArrayBuffer
crypto.SHA1(message)
Performs a SHA1 hash and returns the result as a 20 byte ArrayBuffer
Note: This is only available in some devices: devices with TLS and SSL support (Espruino Pico only)
message The message to apply the hash to
Returns a 20 byte ArrayBuffer
crypto.SHA224(message)
Performs a SHA224 hash and returns the result as a 28 byte ArrayBuffer
Note: This is only available in some devices: devices with TLS and SSL support (Espruino Pico only)
message The message to apply the hash to
Returns a 20 byte ArrayBuffer
crypto.SHA256(message)
Performs a SHA256 hash and returns the result as a 32 byte ArrayBuffer
Note: This is only available in some devices: devices with TLS and SSL support (Espruino Pico only)
message The message to apply the hash to
Returns a 20 byte ArrayBuffer
crypto.SHA384(message)
Performs a SHA384 hash and returns the result as a 48 byte ArrayBuffer
Note: This is only available in some devices: devices with TLS and SSL support (Espruino Pico only)
message The message to apply the hash to
Returns a 20 byte ArrayBuffer
crypto.SHA512(message)
Performs a SHA512 hash and returns the result as a 64 byte ArrayBuffer
Note: This is only available in some devices: devices with TLS and SSL support (Espruino Pico only)
message The message to apply the hash to
Returns a 32 byte ArrayBuffer
The built-in class for handling Dates
new Date(args, ...)
Creates a date object
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]
A Date object
This function is used in the following places in Espruino's documentation
function Date.getDate()
Day of the month 1..31
See description above
function Date.getDay()
Day of the week (0=sunday, 1=monday, etc)
See description above
function Date.getFullYear()
The year, eg. 2014
See description above
function Date.getHours()
0..23
See description above
function Date.getMilliseconds()
0..999
See description above
function Date.getMinutes()
0..59
See description above
function Date.getMonth()
Month of the year 0..11
See description above
function Date.getSeconds()
0..59
See description above
function Date.getTime()
Return the number of milliseconds since 1970
See description above
function Date.getTimezoneOffset()
The getTimezoneOffset() method returns the time-zone offset from UTC, in minutes, for the current locale.
The difference, in minutes, between UTC and local time
Date.now()
Get the number of milliseconds elapsed since 1970 (or on embedded platforms, since startup)
See description above
Date.parse(str)
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'
str A String
The number of milliseconds since 1970
This function is used in the following places in Espruino's documentation
function Date.toString()
Converts to a String, eg: Fri Jun 20 2014 14:52:20 GMT+0000
Note: This always assumes a timezone of GMT+0000
A String
function Date.toUTCString()
Converts to a String, eg: Fri, 20 Jun 2014 14:52:20 GMT
Note: This always assumes a timezone of GMT
A String
function Date.valueOf()
Return the number of milliseconds since 1970
See description above
This is the built-in JavaScript class for Espruino utility functions.
E.clip(x, min, max)
Clip a number to be between min and max (inclusive)
Note: This is only available in some devices: not devices with low flash memory
x A floating point value to clip
min The smallest the value should be
max The largest the value should be
The value of x, clipped so as not to be below min or above max.
This function is used in the following places in Espruino's documentation
E.connectSDCard(spi, csPin)
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
spi The SPI object to use for communication
csPin The pin to use for Chip Select
This function is used in the following places in Espruino's documentation
E.convolve(arr1, arr2, offset)
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
arr1 An array to convolve
arr2 An array to convolve
offset The mean value of the array
The variance of the given buffer
E.dumpStr()
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
A String
E.dumpTimers()
Output the current list of Utility Timer Tasks - for debugging only
Note: This is only available in some devices: not release builds
E.enableWatchdog(timeout)
Enable the watchdog timer. This will reset Espruino if it isn't able to return to the idle loop within the timeout. 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 available in some devices: not devices with low flash memory
timeout The timeout in seconds before a watchdog reset
E.FFT(arrReal, arrImage, inverse)
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(rr+ii).
Note: This is only available in some devices: not devices with low flash memory
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()
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
The voltage (in Volts) that a reading of 1 from analogRead actually represents - usually around 3.3v
This function is used in the following places in Espruino's documentation
E.getErrorFlags()
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
An array of error flags
E.getSizeOf(v, depth)
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(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
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
Information about the variable size - see below
E.getTemperature()
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.
The temperature in degrees C
This function is used in the following places in Espruino's documentation
E.HSBtoRGB(hue, sat, bri)
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
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
A 24 bit number containing bytes representing red, green, and blue: 0xBBGGRR
E.hwRand()
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
A random number
E.on('init', function() { ... });
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(array, index)
Interpolate between two adjacent values in the Typed Array
Note: This is only available in some devices: not devices with low flash memory
array A Typed Array to interpolate between
index Floating point index to access
The result of interpolating between (int)index and (int)(index+1)
E.interpolate2d(array, width, x, y)
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
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
The result of interpolating in 2d between the 4 surrounding cells
E.mapInPlace(from, to, map, bits)
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
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(addr, len)
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.
addr The address of the memory area
len The length (in bytes) of the memory area
A Uint8Array
E.nativeCall(addr, sig, data)
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
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.
The native function
This function is used in the following places in Espruino's documentation
E.openFile(path, mode)
Open a file
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'.
A File object
This function is used in the following places in Espruino's documentation
E.reverseByte(x)
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
x A byte value to reverse the bits of
The byte with reversed bits
E.sendUSBHID(data)
data An array of bytes to send as a USB HID packet
1 on success, 0 on failure
E.setUSBHID(opts)
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 Espruino Pico)
opts An object containing at least reportDescriptor, an array representing the report descriptor. Pass undefined to disable HID.
E.srand(v)
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
v The 32 bit integer seed to use for the random number generator
E.sum(arr)
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
arr The array to sum
The sum of the given buffer
This function is used in the following places in Espruino's documentation
E.toArrayBuffer(str)
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('....')).
str The string to convert to an ArrayBuffer
An ArrayBuffer that uses the given string
This function is used in the following places in Espruino's documentation
E.toString(args, ...)
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.
args, ... The arguments to convert to a String
A String
This function is used in the following places in Espruino's documentation
E.toUint8Array(args, ...)
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.
args, ... The arguments to convert to a Uint8Array
A Uint8Array
E.unmountSD()
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(arr, mean)
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
arr The array to work out the variance for
mean The mean value of the array
The variance of the given buffer
The base class for runtime errors
new Error(message)
Creates an Error object
message An optional message string
An Error object
function Error.toString()
A String
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.
ESP8266.crc32(arrayOfData)
arrayOfData Array of data to CRC
32-bit CRC
ESP8266.dumpSocketInfo()
Dumps info about all sockets to the log. This is for troubleshooting the socket implementation.
ESP8266.getFreeFlash()
Array of objects with addr and length properties describing the free flash areas available
ESP8266.getResetInfo()
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 causeepc1, epc2, epc3: instruction pointersexcvaddr: address being accesseddepc: (?)An object with the reset cause information
ESP8266.getState()
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 integerflashChip - Type of flash chip as string with manufacturer & chip, ex: '0xEF 0x4016`The state of the ESP8266
ESP8266.logDebug(enable)
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).
enable Enable or disable the debug logging.
ESP8266.neopixelWrite(pin, arrayOfData)
pin Pin for output signal.
arrayOfData Array of LED data.
ESP8266.ping(ipAddr, pingCallback)
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?
ipAddr A string representation of an IP address.
pingCallback Optional callback function.
ESP8266.printLog()
Prints the contents of the debug log to the console.
ESP8266.readLog()
Returns one line from the log or up to 128 characters.
ESP8266.reboot()
Perform a hardware reset/reboot of the esp8266.
ESP8266.setCPUFreq(freq)
Set the operating frequency of the ESP8266 processor.
freq Desired frequency - either 80 or 160.
ESP8266.setLog(mode)
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.
mode Debug log mode: 0=off, 1=in-memory only, 2=in-mem and uart0, 3=in-mem and uart1.
An instantiation of an Ethernet network adaptor
function Ethernet.getIP()
Get the current IP address, subnet, gateway and mac address.
See description above
function Ethernet.setIP(options)
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"
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.
True on success
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.
function File.close()
Close an open file.
function File.pipe(destination, options)
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
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(length)
Read data in a file in byte size chunks
length is an integer specifying the number of bytes to read.
A string containing the characters that were read
This function is used in the following places in Espruino's documentation
function File.seek(nBytes)
Seek to a certain position in the file
nBytes is an integer specifying the number of bytes to skip forwards.
function File.skip(nBytes)
Skip the specified number of bytes forward in the file
nBytes is a positive integer specifying the number of bytes to skip forwards.
function File.write(buffer)
write data to a file
buffer A string containing the bytes to write
the number of bytes written
This function is used in the following places in Espruino's documentation
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().
Flash.erasePage(addr)
Erase a page of flash memory
Note: This is only available in some devices: not devices with low flash memory
addr An address in the page that is to be erased
Flash.getPage(addr)
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
addr An address in memory
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(length, addr)
Read flash memory from the given address
Note: This is only available in some devices: not devices with low flash memory
length The amount of data to read (in bytes)
addr The address to start writing from
A Uint8Array of data
Flash.write(data, addr)
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
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)
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).
new Float32Array(arr, byteOffset, length)
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.
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)
A typed array
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).
new Float64Array(arr, byteOffset, length)
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.
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)
A typed array
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
fs.appendFile(path, data)
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.
path The path of the file to write
data The data to write to the file
True on success, false on failure
fs.appendFileSync(path, data)
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
path The path of the file to write
data The data to write to the file
True on success, false on failure
This function is used in the following places in Espruino's documentation
fs.pipe(source, destination, options)
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(path)
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.
path The path of the directory to list. If it is not supplied, '' is assumed, which will list the root directory
An array of filename strings (or undefined if the directory couldn't be listed)
This function is used in the following places in Espruino's documentation
fs.readdirSync(path)
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
path The path of the directory to list. If it is not supplied, '' is assumed, which will list the root directory
An array of filename strings (or undefined if the directory couldn't be listed)
This function is used in the following places in Espruino's documentation
fs.readFile(path)
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.
path The path of the file to read
A string containing the contents of the file (or undefined if the file doesn't exist)
This function is used in the following places in Espruino's documentation
fs.readFileSync(path)
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
path The path of the file to read
A string containing the contents of the file (or undefined if the file doesn't exist)
This function is used in the following places in Espruino's documentation
fs.statSync(path)
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
path The path of the file to get information on
An object describing the file, or undefined on failure
fs.unlink(path)
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
path The path of the file to delete
True on success, or false on failure
fs.unlinkSync(path)
Delete the given file
Note: This is only available in some devices: not devices with low flash memory
path The path of the file to delete
True on success, or false on failure
fs.writeFile(path, data)
Write the data to the given file
NOTE: Espruino does not yet support Async file IO, so this function behaves like the 'Sync' version.
path The path of the file to write
data The data to write to the file
True on success, false on failure
fs.writeFileSync(path, data)
Write the data to the given file
Note: This is only available in some devices: not devices with low flash memory
path The path of the file to write
data The data to write to the file
True on success, false on failure
This function is used in the following places in Espruino's documentation
This is the built-in class for Functions
function Function.apply(this, args)
This executes the function with the supplied 'this' argument and parameters
this The value to use as the 'this' argument when executing the function
args Optional Array of Arguments
The return value of executing this function
function Function.bind(this, params, ...)
This executes the function with the supplied 'this' argument and parameters
this The value to use as the 'this' argument when executing the function
params, ... Optional Default parameters that are prepended to the call
The 'bound' function
This function is used in the following places in Espruino's documentation
function Function.call(this, params, ...)
This executes the function with the supplied 'this' argument and parameters
this The value to use as the 'this' argument when executing the function
params, ... Optional Parameters
The return value of executing this function
new Function(args, ...)
Creates a function
args, ... Zero or more arguments (as strings), followed by a string representing the code to run
A Number object
function Function.replaceWith(newFunc)
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.
newFunc The new function to replace this function with
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)
function Graphics.clear()
Clear the LCD with the Background Color
This function is used in the following places in Espruino's documentation
Graphics.createArrayBuffer(width, height, bpp, options)
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
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
The new Graphics object
This function is used in the following places in Espruino's documentation
Graphics.createCallback(width, height, bpp, callback)
Create a Graphics object that renders by calling a JavaScript callback function to draw pixels
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.
The new Graphics object
This function is used in the following places in Espruino's documentation
Graphics.createSDL(width, height)
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
width Pixels wide
height Pixels high
The new Graphics object
function Graphics.drawImage(image, x, y)
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
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
This function is used in the following places in Espruino's documentation
function Graphics.drawLine(x1, y1, x2, y2)
Draw a line between x1,y1 and x2,y2 in the current foreground color
x1 The left
y1 The top
x2 The right
y2 The bottom
This function is used in the following places in Espruino's documentation
function Graphics.drawRect(x1, y1, x2, y2)
Draw an unfilled rectangle 1px wide in the Foreground Color
x1 The left
y1 The top
x2 The right
y2 The bottom
function Graphics.drawString(str, x, y)
Draw a string of text in the current font
str The string
x The left
y The top
function Graphics.fillPoly(poly)
Draw a filled polygon in the current foreground color
poly An array of vertices, of the form
[x1,y1,x2,y2,x3,y3,etc]
function Graphics.fillRect(x1, y1, x2, y2)
Fill a rectangular area in the Foreground Color
x1 The left
y1 The top
x2 The right
y2 The bottom
function Graphics.getBgColor()
Get the background color to use for subsequent drawing operations
The integer value of the colour
function Graphics.getColor()
Get the color to use for subsequent drawing operations
The integer value of the colour
function Graphics.getHeight()
The height of the LCD
The height of the LCD
function Graphics.getModified(reset)
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}
reset Whether to reset the modified area or not
An object {x1,y1,x2,y2} containing the modified area, or undefined if not modified
function Graphics.getPixel(x, y)
Get a pixel's color
x The left
y The top
The color
function Graphics.getWidth()
The width of the LCD
The width of the LCD
function Graphics.lineTo(x, y)
Draw a line from the last position of lineTo or moveTo to this position
x X value
y Y value
function Graphics.moveTo(x, y)
Move the cursor to a position - see lineTo
x X value
y Y value
function Graphics.setBgColor(r, g, b)
Set the background color to use for subsequent drawing operations
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(r, g, b)
Set the color to use for subsequent drawing operations
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)
This function is used in the following places in Espruino's documentation
function Graphics.setFontBitmap()
Set Graphics to draw with a Bitmapped Font
function Graphics.setFontCustom(bitmap, firstChar, width, height)
Set Graphics to draw with a Custom Font
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(size)
Set Graphics to draw with a Vector Font of the given size
Note: This is only available in some devices: not devices with low flash memory
size The size as an integer
function Graphics.setPixel(x, y, col)
Set a pixel's color
x The left
y The top
col The color
function Graphics.setRotation(rotation, reflect)
Set the current rotation of the graphics device.
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(str)
Return the size in pixels of a string of text in the current font
str The string
The length of the string in pixels
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.
function HASH.digest(message)
message part of message
Hash digest
function HASH.hexdigest(message)
message part of message
Hash hexdigest
function HASH.update(message)
message part of message
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.
hashlib.sha224(message)
message message to hash
Returns a new HASH SHA224 Object
hashlib.sha256(message)
message message to hash
Returns a new HASH SHA256 Object
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.
http.createServer(callback)
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
callback A function(request,response) that will be called when a connection is made
Returns a new httpSrv object
This function is used in the following places in Espruino's documentation
http.get(options, callback)
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.
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 a new httpCRq object
This function is used in the following places in Espruino's documentation
http.request(options, callback)
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.
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 a new httpCRq object
This function is used in the following places in Espruino's documentation
The HTTP client request, returned by http.request() and http.get().
httpCRq.on('drain', function() { ... });
An event that is fired when the buffer is empty and it can accept more data to send.
function httpCRq.end(data)
Finish this HTTP request - optional data to append as an argument
data A string containing data to send
httpCRq.on('error', function() { ... });
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(data)
data A string containing data to send
For note compatibility, the boolean false. When the send buffer is empty, a drain event will be sent
The HTTP client response, passed to the callback of http.request() an http.get().
function httpCRs.available()
Return how many bytes are available to read. If there is a 'data' event handler, this will always return 0.
How many bytes are available
httpCRs.on('close', function() { ... });
Called when the connection closes with one hadError boolean parameter, which indicates whether an error occurred.
httpCRs.on('data', function(data) { ... });
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()
data A string containing one or more characters of received data
httpCRs.on('error', function() { ... });
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(destination, options)
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
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(chars)
Return a string containing characters that have been received
chars The number of characters to read, or undefined/0 for all available
A string containing the required bytes.
The HTTP server request
function httpSRq.available()
Return how many bytes are available to read. If there is already a listener for data, this will always return 0.
How many bytes are available
httpSRq.on('close', function() { ... });
Called when the connection closes.
httpSRq.on('data', function(data) { ... });
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()
data A string containing one or more characters of received data
function httpSRq.pipe(destination, options)
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
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(chars)
Return a string containing characters that have been received
chars The number of characters to read, or undefined/0 for all available
A string containing the required bytes.
The HTTP server response
httpSRs.on('close', function() { ... });
Called when the connection closes.
httpSRs.on('drain', function() { ... });
An event that is fired when the buffer is empty and it can accept more data to send.
function httpSRs.end(data)
data A string containing data to send
function httpSRs.write(data)
data A string containing data to send
For note compatibility, the boolean false. When the send buffer is empty, a drain event will be sent
function httpSRs.writeHead(statusCode, headers)
statusCode The HTTP status code
headers An object containing the headers
The HTTP server created by require('http').createServer
function httpSrv.close()
Stop listening for new HTTP connections
function httpSrv.listen(port)
Start listening for new HTTP connections on the given port
port The port to listen on
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.
I2C1
The first I2C port
I2C2
The second I2C port
I2C3
The third I2C port
I2C.find(pin)
Try and find an I2C hardware device that will work on this pin (eg. I2C1)
May return undefined if no device can be found.
pin A pin to search with
An object of type I2C, or undefined if one couldn't be found.
function I2C.readFrom(address, quantity)
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
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
The data that was returned - as a Uint8Array
function I2C.setup(options)
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)
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.
This function is used in the following places in Espruino's documentation
function I2C.writeTo(address, data, ...)
Transmit to the slave device with the given address. This is like Arduino's beginTransmission, write, and endTransmission rolled up into one.
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:#}.
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).
new Int16Array(arr, byteOffset, length)
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.
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)
A typed array
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).
new Int32Array(arr, byteOffset, length)
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.
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)
A typed array
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).
new Int8Array(arr, byteOffset, length)
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.
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)
A typed array
The base class for internal errors
new InternalError(message)
Creates an InternalError object
message An optional message string
An InternalError object
function InternalError.toString()
A String
An Object that handles conversion to and from the JSON data interchange format
JSON.parse(string)
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.
string A JSON string
The JavaScript object created by parsing the data string
This function is used in the following places in Espruino's documentation
JSON.stringify(data)
Convert the given object into a JSON string which can subsequently be parsed with JSON.parse or eval
data The data to be converted to a JSON string
A JSON string
This function is used in the following places in Espruino's documentation
This is a standard JavaScript class that contains useful Maths routines
Math.abs(x)
x A floating point value
The absolute value of x (eg,
Math.abs(2)==2, but also
Math.abs(-2)==2)
This function is used in the following places in Espruino's documentation
Math.acos(x)
x The value to get the arc cosine of
The arc cosine of x, between 0 and PI
Math.asin(x)
x The value to get the arc sine of
The arc sine of x, between -PI/2 and PI/2
Math.atan(x)
x The value to get the arc tangent of
The arc tangent of x, between -PI/2 and PI/2
Math.atan2(y, x)
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
The arctangent of Y/X, between -PI and PI
Math.ceil(x)
x The value to round up
x, rounded upwards to the nearest integer
Math.clip(x, min, max)
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
x A floating point value to clip
min The smallest the value should be
max The largest the value should be
The value of x, clipped so as not to be below min or above max.
Math.cos(theta)
theta The angle to get the cosine of
The cosine of theta
This function is used in the following places in Espruino's documentation
Math.E
The value of E - 2.718281828459045
Math.exp(x)
x The value raise E to the power of
E^x
Math.floor(x)
x The value to round down
x, rounded downwards to the nearest integer
This function is used in the following places in Espruino's documentation
Math.LN10
The natural logarithm of 10 - 2.302585092994046
Math.LN2
The natural logarithm of 2 - 0.6931471805599453
Math.log(x)
x The value to take the logarithm (base E) root of
The log (base E) of x
This function is used in the following places in Espruino's documentation
Math.LOG10E
The base 10 logarithm of e - 0.4342944819032518
Math.LOG2E
The base 2 logarithm of e - 1.4426950408889634
Math.max(args, ...)
Find the maximum of a series of numbers
args, ... A floating point value to clip
The maximum of the supplied values
This function is used in the following places in Espruino's documentation
Math.min(args, ...)
Find the minimum of a series of numbers
args, ... A floating point value to clip
The minimum of the supplied values
This function is used in the following places in Espruino's documentation
Math.PI
The value of PI - 3.141592653589793
Math.pow(x, y)
x The value to raise to the power
y The power x should be raised to
x raised to the power y (x^y)
Math.random()
A random number between 0 and 1
This function is used in the following places in Espruino's documentation
Math.round(x)
x The value to round
x, rounded to the nearest integer
This function is used in the following places in Espruino's documentation
Math.sin(theta)
theta The angle to get the sine of
The sine of theta
This function is used in the following places in Espruino's documentation
Math.sqrt(x)
x The value to take the square root of
The square root of x
Math.SQRT1_2
The square root of 1/2 - 0.7071067811865476
Math.SQRT2
The square root of 2 - 1.4142135623730951
Math.tan(theta)
theta The angle to get the tangent of
The tangent of theta
Math.wrap(x, max)
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
x A floating point value to wrap
max The largest the value should be
The value of x, wrapped so as not to be below min or above max.
This function is used in the following places in Espruino's documentation
Built-in class that caches the modules used by the require command
Modules.addCached(id, sourcecode)
Add the given module to the cache
id The module name to add
sourcecode The module's sourcecode
Modules.getCached()
Return an array of module names that have been cached
An array of module names
Modules.removeAllCached()
Remove all cached modules
Modules.removeCached(id)
Remove the given module from the list of cached modules
id The module name to remove
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.
net.connect(options, callback)
Create a socket connection
options An object containing host,port fields
callback A function(socket) 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 a new net.Socket object
net.createServer(callback)
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
callback A function(connection) that will be called when a connection is made
Returns a new Server Object
Library that initialises a network device that calls into JavaScript
NetworkJS.create(obj)
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;
}
});
obj An object containing functions to access the network device
The object passed in
This is the built-in class for the Arduino-style pin namings on ST Nucleo boards
Nucleo.A0
A Pin
Nucleo.A1
A Pin
Nucleo.A2
A Pin
Nucleo.A3
A Pin
Nucleo.A4
A Pin
Nucleo.A5
A Pin
Nucleo.D0
A Pin
Nucleo.D1
A Pin
Nucleo.D10
A Pin
Nucleo.D11
A Pin
Nucleo.D12
A Pin
Nucleo.D13
A Pin
Nucleo.D14
A Pin
Nucleo.D15
A Pin
Nucleo.D2
A Pin
Nucleo.D3
A Pin
Nucleo.D4
A Pin
Nucleo.D5
A Pin
Nucleo.D6
A Pin
Nucleo.D7
A Pin
Nucleo.D8
A Pin
Nucleo.D9
A Pin
This is the built-in JavaScript class for numbers.
Number.MAX_VALUE
Maximum representable value
Number.MIN_VALUE
Smallest representable value
Number.NaN
Not a Number
Number.NEGATIVE_INFINITY
Negative Infinity (-1/0)
new Number(value, ...)
Creates a number
value, ... A single value to be converted to a number
A Number object
Number.POSITIVE_INFINITY
Positive Infinity (1/0)
function Number.toFixed(decimalPlaces)
Format the number as a fixed point number
decimalPlaces A number between 0 and 20 specifying the number of decimal digits after the decimal point
A string
This is the built-in class for Objects
function Object.clone()
Copy this object completely
A copy of this Object
Object.create(proto)
Creates a new object with the specified prototype object and properties. properties are currently unsupported.
proto A prototype object
A new object
Object.defineProperties(obj, props)
Adds new properties to the Object. See Object.defineProperty for more information
obj An object
props An object whose fields represent property names, and whose values are property descriptors.
The object, obj.
Object.defineProperty(obj, name, desc)
Add a new property to the Object. 'Desc' is an object with the following fields:
configurable (bool = false) - can this property be changed/deletedenumerable (bool = false) - can this property be enumeratedvalue (anything) - the value of this propertywritable (bool = false) - can the value be changed with the assignment operator?get (function) - the getter function, or undefined if no getterset (function) - the setter function, or undefined if no setter*
Note: configurable, enumerable, writable, get, and set are not implemented and will be ignored.
obj An object
name The name of the property
desc The property descriptor
The object, obj.
function Object.emit(event, args, ...)
Call the event listeners for this object, for instance
http.emit('data', 'Foo'). See Node.js's EventEmitter.
event The name of the event, for instance 'data'
args, ... Optional arguments
Object.getOwnPropertyDescriptor(obj, name)
Get information on the given property in the object, or undefined
obj The object
name The name of the property
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(object)
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
object The Object to return a list of property names for
An array of the Object's own properties
function Object.hasOwnProperty(name)
Return true if the object (not its prototype) has the given property.
NOTE: This currently returns false-positives for built-in functions in prototypes
name The name of the property to search for
True if it exists, false if it doesn't
Object.keys(object)
Return all enumerable keys of the given object
object The object to return keys for
An array of strings - one for each key on the given object
property Object.length
Find the length of the object
The length of the object
new Object(value)
Creates an Object from the supplied argument
value A single value to be converted to an object
An Object
function Object.on(event, listener)
Register an event listener for this object, for instance
http.on('data', function(d) {...}). See Node.js's EventEmitter.
event The name of the event, for instance 'data'
listener The listener to call when this event is received
This function is used in the following places in Espruino's documentation
function Object.removeAllListeners(event)
Removes all listeners, or those of the specified event.
event The name of the event, for instance 'data'
This function is used in the following places in Espruino's documentation
function Object.toString(radix)
Convert the Object to a string
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.
A String representing the object
function Object.valueOf()
Returns the primitive value of this object.
The primitive value of this object
This class provides a software-defined OneWire master. It is designed to be similar to Arduino's OneWire library.
new OneWire(pin)
Create a software OneWire implementation on the given pin
pin The pin to implement OneWire on
A OneWire object
function OneWire.read(count)
Read a byte
count (optional) The amount of bytes to read
The byte that was read, or a Uint8Array if count was specified and >=0
function OneWire.reset()
Perform a reset cycle
True is a device was present (it held the bus low)
function OneWire.search()
Search for devices
An array of devices that were found
This function is used in the following places in Espruino's documentation
function OneWire.search(command)
Search for devices
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'
An array of devices that were found
This function is used in the following places in Espruino's documentation
function OneWire.select(rom)
Select a ROM - reset needs to be done first
rom The device to select (get this using OneWire.search())
function OneWire.skip()
Skip a ROM
function OneWire.write(data, power)
Write one or more bytes
data A byte (or array of bytes) to write
power Whether to leave power on after write (default is false)
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
function Pin.getInfo()
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
An object containing information about this pins
function Pin.getMode()
Return the current mode of the given pin. See pinMode for more information.
The pin mode, as a string
function Pin.mode(mode)
Set the mode of the given pin. See pinMode for more information on pin modes.
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.
new Pin(value)
Creates a pin from the given argument (or returns undefined if no argument)
value A value to be converted to a pin. Can be a number, pin, or String.
A Pin object
function Pin.read()
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"
Whether pin is a logical 1 or 0
function Pin.reset()
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()
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(value)
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"
value Whether to set output high (true/1) or low (false/0)
function Pin.writeAtTime(value, time)
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
value Whether to set output high (true/1) or low (false/0)
time Time at which to write
This class contains information about Espruino itself
process.env
Returns an Object containing various pre-defined variables. standard ones are BOARD, VERSION
An object
process.memory()
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.
Information about memory usage
This function is used in the following places in Espruino's documentation
process.version
Returns the version of Espruino as a String
The version of Espruino
The base class for reference errors - where a variable
which doesn't exist has been accessed.
new ReferenceError(message)
Creates a ReferenceError object
message An optional message string
A ReferenceError object
function ReferenceError.toString()
A String
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
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
USB
The USB Serial port
function Serial.available()
Return how many bytes are available to read. If there is already a listener for data, this will always return 0.
How many bytes are available
Serial.on('data', function(data) { ... });
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()
data A string containing one or more characters of received data
Serial.find(pin)
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.
pin A pin to search with
An object of type Serial, or undefined if one couldn't be found.
Serial.on('framing', function() { ... });
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(function)
Serial.onData(func) has now been replaced with the event Serial.on(data, func)
function
Serial.on('parity', function() { ... });
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(destination, options)
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
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(string)
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.
string A String to print
This function is used in the following places in Espruino's documentation
function Serial.println(string)
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, use Serial.write`.
string A String to print
This function is used in the following places in Espruino's documentation
function Serial.read(chars)
Return a string containing characters that have been received
chars The number of characters to read, or undefined/0 for all available
A string containing the required bytes.
function Serial.setConsole()
Set this Serial port as the port for the console
This function is used in the following places in Espruino's documentation
function Serial.setup(baudrate, options)
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)
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'}
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
This function is used in the following places in Espruino's documentation
function Serial.write(data, ...)
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.
data, ... One or more items to write. May be ints, strings, arrays, or objects of the form {data: ..., count:#}.
This function is used in the following places in Espruino's documentation
The socket server created by require('net').createServer
function Server.close()
Stop listening for new connections
function Server.listen(port)
Start listening for new connections on the given port
port The port to listen on
An actual socket connection - allowing transmit/receive of TCP data
function Socket.available()
Return how many bytes are available to read. If there is already a listener for data, this will always return 0.
How many bytes are available
Socket.on('close', function(had_error) { ... });
Called when the connection closes.
had_error A boolean indicating whether the connection had an error (use an error event handler to get error details).
Socket.on('data', function(data) { ... });
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()
data A string containing one or more characters of received data
Socket.on('drain', function() { ... });
An event that is fired when the buffer is empty and it can accept more data to send.
function Socket.end(data)
Close this socket - optional data to append as an argument
data A string containing data to send
Socket.on('error', function(details) { ... });
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:
details An error object with an error code (a negative integer) and a message.
function Socket.pipe(destination, options)
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
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(chars)
Return a string containing characters that have been received
chars The number of characters to read, or undefined/0 for all available
A string containing the required bytes.
function Socket.write(data)
data A string containing data to send
For note compatibility, the boolean false. When the send buffer is empty, a drain event will be sent
This class allows use of the built-in SPI ports. Currently it is SPI master only.
SPI1
The first SPI port
SPI2
The second SPI port
SPI3
The third SPI port
SPI.find(pin)
Try and find an SPI hardware device that will work on this pin (eg. SPI1)
May return undefined if no device can be found.
pin A pin to search with
An object of type SPI, or undefined if one couldn't be found.
function SPI.send(data, nss_pin)
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]
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.
The data that was returned
This function is used in the following places in Espruino's documentation
function SPI.send4bit(data, bit0, bit1, nss_pin)
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.
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.
This function is used in the following places in Espruino's documentation
function SPI.send8bit(data, bit0, bit1, nss_pin)
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
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(options)
Set up this SPI port as an SPI Master.
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.
This function is used in the following places in Espruino's documentation
new SPI()
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(data, ...)
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.
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
This is the built-in class for Text Strings.
Text Strings in Espruino are not zero-terminated, so you can store zeros in them.
function String.charAt(pos)
Return a single character at the given position in the String.
pos The character number in the string. Negative values return characters from end of string (-1 = last char)
The character in the string
function String.charCodeAt(pos)
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
pos The character number in the string. Negative values return characters from end of string (-1 = last char)
The integer value of a character in the string
String.fromCharCode(code, ...)
Return the character(s) represented by the given character code(s).
code, ... One or more character codes to create a string from (range 0-255).
The character
This function is used in the following places in Espruino's documentation
function String.indexOf(substring, fromIndex)
Return the index of substring in this string, or -1 if not found
substring The string to search for
fromIndex Index to search from
The index of the string, or -1 if not found
This function is used in the following places in Espruino's documentation
function String.lastIndexOf(substring, fromIndex)
Return the last index of substring in this string, or -1 if not found
substring The string to search for
fromIndex Index to search from
The index of the string, or -1 if not found
property String.length
Find the length of the string
The value of the string
function String.replace(subStr, newSubStr)
Search and replace ONE occurrance of subStr with newSubStr and return the result. This doesn't alter the original string. Regular expressions not supported.
subStr The string to search for
newSubStr The string to replace it with
This string with subStr replaced
function String.slice(start, end)
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
Part of this string from start for len characters
function String.split(separator)
Return an array made by splitting this string up by the separator. eg.
'1,2,3'.split(',')==[1,2,3]
separator The start character index
Part of this string from start for len characters
new String(str, ...)
Create a new String
str, ... A value to turn into a string. If undefined or not supplied, an empty String is created.
A String
function String.substr(start, len)
start The start character index
len The number of characters
Part of this string from start for len characters
function String.substring(start, end)
start The start character index
end The end character index
The part of this string between start and end
function String.toLowerCase()
The lowercase version of this string
function String.toUpperCase()
The uppercase version of this string
function String.trim()
Return a new string with any whitespace (tabs, space, form feed, newline,
carriage return, etc) removed from the beginning and end.
A String with Whitespace removed from the beginning and end
The base class for syntax errors
new SyntaxError(message)
Creates a SyntaxError object
message An optional message string
A SyntaxError object
function SyntaxError.toString()
A String
This library implements a telnet console for the Espruino interpreter. It requires a network
connection, e.g. Wifi, and current is only available on the ESP8266.
Telnet.setOptions(options)
options Options controlling the telnet console server
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.
tls.connect(options, callback)
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 and it will be loaded and parsed if you have an SD card connected. For instance options.key = "key.pem";.
For more information about generating and using certificates, see:
https://engineering.circle.com/https-authorized-certs-with-node-js/
Note: This is only available in some devices: devices with TLS and SSL support (Espruino Pico only)
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 a new net.Socket object
This library provides TV out capability on the Espruino and Espruino Pico.
See the [[Television]] page for more information.
tv.setup(options, width)
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.
options Various options for the TV output
width
A graphics object
This function is used in the following places in Espruino's documentation
The base class for type errors
function TypeError.toString()
A String
new TypeError(message)
Creates a TypeError object
message An optional message string
A TypeError object
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).
new Uint16Array(arr, byteOffset, length)
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.
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)
A typed array
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).
new Uint32Array(arr, byteOffset, length)
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.
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)
A typed array
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).
new Uint8Array(arr, byteOffset, length)
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.
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)
A typed array
This function is used in the following places in Espruino's documentation
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).
new Uint8ClampedArray(arr, byteOffset, length)
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.
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)
A typed array
This class helps to convert URLs into Objects of information ready for http.request/get
url.parse(urlStr, parseQuery)
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"}}
urlStr A URL to be parsed
parseQuery Whether to parse the query string into an object not (default = false)
An object containing options for
http.request or
http.get. Contains method, host, path, pathname, search, port and query
This function is used in the following places in Espruino's documentation
This class handles waveforms. In Espruino, a Waveform is a set of data that you want to input or output.
function Waveform.startInput(output, freq, options)
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
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 boolean specifying whether to repeat the give sample
function Waveform.startOutput(output, freq, options)
Will start outputting the waveform on the given pin - the pin must have previously been initialised with analogWrite. 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
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 boolean specifying whether to repeat the give sample
function Waveform.stop()
Stop a waveform that is currently outputting
Note: This is only available in some devices: not devices with low flash memory
new Waveform(samples, options)
Create a waveform class. This allows high speed input and output of waveforms. It has an internal variable called buffer (as well as buffer2 when double-buffered - see options below) which contains the data to input/output.
When double-buffered, a 'buffer' event will be emitted each time a buffer is finished with (the argument is that buffer). When the recording stops, a 'finish' event will be emitted (with the first argument as the buffer).
Note: This is only available in some devices: not devices with low flash memory
samples The number of samples
options Optional options struct {doubleBuffer:bool, bits : 8/16} where: doubleBuffer is whether to allocate two buffers or not (default false), and bits is the amount of bits to use (default 8).
An Waveform object
The wifi library is a generic cross-platform library to control the Wifi interface. It supports functionality such as connecting to wifi networks, getting network information, starting and access point, etc.
Currently this library is ESP8266 specific and needs to be ported to other Espruino platforms.
To get started and connect to your local access point all you need is
var wifi = require("Wifi");
wifi.connect("my-ssid", {password:"my-pwd"}, function(ap){ console.log("connected:", ap); });
If you want the connection to happen automatically at boot, add wifi.save();.
Wifi.on('associated', function(details) { ... });
The 'connected' event is called when an association with an access point has succeeded, i.e., a connection to the AP's network has been established.
The details include:
details An object with event details
Wifi.on('auth_change', function(details) { ... });
The 'auth_change' event is called when the authentication mode with the associated access point changes.
The details include:
oldMode - The old auth mode (string: open, wep, wpa, wpa2, wpa_wpa2)
newMode - The new auth mode (string: open, wep, wpa, wpa2, wpa_wpa2)
details An object with event details
Wifi.connect(ssid, options, callback)
Connect to an access point as a station. If there is an existing connection to an AP it is first disconnected if the SSID or password are different from those passed as parameters. Put differently, if the passed SSID and password are identical to the currently connected AP then nothing is changed.
When the connection attempt completes the callback function is invoked with one err parameter, which is NULL if there is no error and a string message if there is an error. If DHCP is enabled the callback occurs once an IP addres has been obtained, if a static IP is set the callback occurs once the AP's network has been joined. The callback is also invoked if a connection already exists and does not need to be changed.
The options properties may contain:
password - Password string to be used to access the network.
dnsServers (array of String) - An array of up to two DNS servers in dotted decimal format string.
Notes:
getDetails().status field.connect call automatically enabled station mode, it can be disabled again by calling disconnect.ssid The access point network id.
options Connection options (optional).
callback A function to be called back on completion (optional).
Wifi.on('connected', function(details) { ... });
The 'connected' event is called when the connection with an access point is ready for traffic. In the case of a dynamic IP address configuration this is when an IP address is obtained, in the case of static IP address allocation this happens when an association is formed (in that case the 'associated' and 'connected' events are fired in rapid succession).
The details include:
details An object with event details
Wifi.on('dhcp_timeout', function() { ... });
The 'dhcp_timeout' event is called when a DHCP request to the connected access point fails and thus no IP address could be acquired (or renewed).
Wifi.disconnect(callback)
Disconnect the wifi station from an access point and disable the station mode. It is OK to call disconnect to turn off station mode even if no connection exists (for example, connection attempts may be failing). Station mode can be re-enabled by calling connect or scan.
callback An optional function to be called back on disconnection. The callback function receives no argument.
Wifi.on('disconnected', function(details) { ... });
The 'disconnected' event is called when an association with an access point has been lost.
The details include:
details An object with event details
Wifi.getAPDetails(callback)
Retrieve the current access point configuration and status. The details object has the following properties:
status - Current access point status: enabled or disabledstations - an array of the stations connected to the access point. This array may be empty. Each entry in the array is an object describing the station which, at a minimum contains ip being the IP address of the station.ssid - SSID to broadcast.password - Password for authentication.authMode - the authentication required of stations: open, wpa, wpa2, wpa_wpa2.hidden - True if the SSID is hidden, false otherwise.maxConn - Max number of station connections supported.savedSsid - the SSID to broadcast automatically at boot time, null if the access point is to be disabled at boot.callback An optional function to be called back with the current access point details, i.e. the same object as returned directly. The callback function is more portable than the direct return value.
An object representing the current access point details, if available immediately.
Wifi.getAPIP(callback)
Return the access point IP information in an object which contains:
callback An optional function to be called back with the the IP information, i.e. the same object as returned directly. The callback function is more portable than the direct return value.
An object representing the esp8266's Access Point IP information, if available immediately.
Wifi.getDetails(callback)
Retrieve the wifi station configuration and status details. The details object has the following properties:
status - Details about the wifi station connection, one of off, connecting, wrong_password, no_ap_found, connect_fail, or connected. The off, bad_password and connected states are stable, the other states are transient. The connecting state will either result in connected or one of the error states (bad_password, no_ap_found, connect_fail) and the no_ap_found and connect_fail states will result in a reconnection attempt after some interval.rssi - signal strength of the connected access point in dB, typically in the range -110 to 0, with anything greater than -30 being an excessively strong signal.ssid - SSID of the access point.password - the password used to connect to the access point.authMode - the authentication used: open, wpa, wpa2, wpa_wpa2 (not currently supported).savedSsid - the SSID to connect to automatically at boot time, null if none.callback An optional function to be called back with the wifi details, i.e. the same object as returned directly. The callback function is more portable than the direct return value.
An object representing the wifi station details, if available immediately.
Wifi.getDHCPHostname(callback)
Deprecated, please use getHostname.
callback An optional function to be called back with the hostname, i.e. the same string as returned directly. The callback function is more portable than the direct return value.
The currently configured DHCP hostname, if available immediately.
Wifi.getHostByName(hostname, callback)
Lookup the hostname and invoke a callback with the IP address as integer argument. If the lookup fails, the callback is invoked with a null argument.
Note: only a single hostname lookup can be made at a time, concurrent lookups are not supported.
hostname The hostname to lookup.
callback The callback to invoke when the hostname is returned.
Wifi.getHostname(callback)
Returns the hostname announced to the DHCP server and broadcast via mDNS when connecting to an access point.
callback An optional function to be called back with the hostname, i.e. the same string as returned directly. The callback function is more portable than the direct return value.
The currently configured hostname, if available immediately.
Wifi.getIP(callback)
Return the station IP information in an object as follows:
Note that the ip, netmask, and gw fields are omitted if no connection is established:
callback An optional function to be called back with the IP information, i.e. the same object as returned directly. The callback function is more portable than the direct return value.
An object representing the station IP information, if available immediately.
Wifi.getStatus(callback)
Retrieve the current overall WiFi configuration. This call provides general information that pertains to both station and access point modes. The getDetails and getAPDetails calls provide more in-depth information about the station and access point configurations, respectively. The status object has the following properties:
station - Status of the wifi station: off, connecting, ...ap - Status of the wifi access point: disabled, enabled.mode - The current operation mode: off, sta, ap, sta+ap.phy - Modulation standard configured: 11b, 11g, 11n (the esp8266 docs are not very clear, but it is assumed that 11n means b/g/n). This setting limits the modulations that the radio will use, it does not indicate the current modulation used with a specific access point.powersave - Power saving mode: none (radio is on all the time), ps-poll (radio is off between beacons as determined by the access point's DTIM setting). Note that in 'ap' and 'sta+ap' modes the radio is always on, i.e., no power saving is possible.savedMode - The saved operation mode which will be applied at boot time: off, sta, ap, sta+ap.callback An optional function to be called back with the current Wifi status, i.e. the same object as returned directly. The callback function is more portable than the direct return value.
An object representing the current WiFi status, if available immediately.
Wifi.on('probe_recv', function(details) { ... });
The 'probe_recv' event is called when a probe request is received from some station by the esp8266's access point.
The details include:
mac - The MAC address of the station in string format (00:00:00:00:00:00)
rssi - The signal strength in dB of the probe request
details An object with event details
Wifi.restore()
Restores the saved Wifi configuration from flash. See Wifi.save().
Wifi.save(what)
Save the current wifi configuration (station and access point) to flash and automatically apply this configuration at boot time, unless what=="clear", in which case the saved configuration is cleared such that wifi remains disabled at boot. The saved configuration includes:
what An optional parameter to specify what to save, on the esp8266 the two supported values are clear and sta+ap. The default is sta+ap
Wifi.scan(callback)
Perform a scan for access points. This will enable the station mode if it is not currently enabled. Once the scan is complete the callback function is called with an array of APs found, each AP is an object with:
ssid: SSID string.mac: access point MAC address in 00:00:00:00:00:00 format.authMode: open, wep, wpa, wpa2, or wpa_wpa2.channel: wifi channel 1..13.hidden: true if the SSID is hidden.rssi: signal strength in dB in the range -110..0.Notes:
in order to perform the scan the station mode is turned on and remains on, use Wifi.disconnect() to turn it off again, if desired.
only one scan can be in progress at a time.
callback A function to be called back on completion.
Wifi.setConfig(settings)
Sets a number of global wifi configuration settings. All parameters are optional and which are passed determines which settings are updated.
The settings available are:
phy - Modulation standard to allow: 11b, 11g, 11n (the esp8266 docs are not very clear, but it is assumed that 11n means b/g/n).
powersave - Power saving mode: none (radio is on all the time), ps-poll (radio is off between beacons as determined by the access point's DTIM setting). Note that in 'ap' and 'sta+ap' modes the radio is always on, i.e., no power saving is possible.
Note: esp8266 SDK programmers may be missing an "opmode" option to set the sta/ap/sta+ap operation mode. Please use connect/scan/disconnect/startAP/stopAP, which all set the esp8266 opmode indirectly.
settings An object with the configuration settings to change.
Wifi.setDHCPHostname(hostname)
Deprecated, please use setHostname instead.
hostname The new DHCP hostname.
Wifi.setHostname(hostname)
Set the hostname. Depending on implemenation, the hostname is sent with every DHCP request and is broadcast via mDNS. The DHCP hostname may be visible in the access point and may be forwarded into DNS as hostname.local.
If a DHCP lease currently exists changing the hostname will cause a disconnect and reconnect in order to transmit the change to the DHCP server.
The mDNS announcement also includes an announcement for the "espruino" service.
hostname The new hostname.
Wifi.setSNTP(server, tz_offset)
Starts the SNTP (Simple Network Time Protocol) service to keep the clock synchronized with the specified server. Note that the time zone is really just an offset to UTC and doesn't handle daylight savings time.
The interval determines how often the time server is queried and Espruino's time is synchronized. The initial synchronization occurs asynchronously after setSNTP returns.
server The NTP server to query, for example, us.pool.ntp.org
tz_offset Local time zone offset in the range -11..13.
Wifi.on('sta_joined', function(details) { ... });
The 'sta_joined' event is called when a station establishes an association (i.e. connects) with the esp8266's access point.
The details include:
* mac - The MAC address of the station in string format (00:00:00:00:00:00)
details An object with event details
Wifi.on('sta_left', function(details) { ... });
The 'sta_left' event is called when a station disconnects from the esp8266's access point (or its association times out?).
The details include:
* mac - The MAC address of the station in string format (00:00:00:00:00:00)
details An object with event details
Wifi.startAP(ssid, options, callback)
Create a WiFi access point allowing stations to connect. If the password is NULL or an empty string the access point is open, otherwise it is encrypted.
The callback function is invoked once the access point is set-up and receives one err argument, which is NULL on success and contains an error message string otherwise.
The options object can contain the following properties.
authMode - The authentication mode to use. Can be one of "open", "wpa2", "wpa", "wpa_wpa2". The default is open (but open access points are not recommended).password - The password for connecting stations if authMode is not open.channel - The channel to be used for the access point in the range 1..13. If the device is also connected to an access point as a station then that access point determines the channel.Notes:
the options should include the ability to set the AP IP and associated netmask, this is a future enhancement.
the startAP call automatically enables AP mode. It can be disabled again by calling stopAP.
ssid The network id.
options Configuration options (optional).
callback Optional function to be called when the AP is successfully started.
Wifi.stopAP(callback)
Stop being an access point and disable the AP operation mode. Ap mode can be re-enabled by calling startAP.
callback An optional function to be called back on successful stop. The callback function receives no argument.
Library for communication with the WIZnet Ethernet module
WIZnet.connect(spi, cs)
Initialise the WIZnet module and return an Ethernet object
spi Device to use for SPI (or undefined to use the default)
cs The pin to use for Chip Select
An Ethernet Object
This function is used in the following places in Espruino's documentation
An instantiation of a WiFi network adaptor
function WLAN.connect(ap, key, callback)
Connect to a wireless network
ap Access point name
key WPA2 key (or undefined for unsecured connection)
callback Function to call back with connection status. It has one argument which is one of 'connect'/'disconnect'/'dhcp'
True if connection succeeded, false if it didn't.
function WLAN.disconnect()
Completely uninitialise and power down the CC3000. After this you'll have to use
require("CC3000").connect() again.
function WLAN.getIP()
Get the current IP address
See description above
function WLAN.reconnect()
Completely uninitialise and power down the CC3000, then reconnect to the old access point.
function WLAN.setIP(options)
Set the current IP address for get an IP from DHCP (if no options object is specified).
Note: Changes are written to non-volatile memory, but will only take effect after calling wlan.reconnect()
options Object containing IP address options { ip : '1,2,3,4', subnet, gateway, dns }, or do not supply an object in otder to force DHCP.
True on success