Skip to main content

All-in-One imp API Object and Method List

This list is not yet complete. All objects and methods for impOS™ 36 are included here; objects and methods coming to impOS 38 have not yet been added.

agent

The device-side object which represents the imp’s online agent

agent.on()

Registers a function to process messages sent from the agent to the device

Availability

Device

Returns

Nothing

Parameters

Name Type Description
messageName String The name of the message with which the registered handler will be associated
callback Function The function that will be called when the named message is received.
It will be called with the following parameter(s):
Name Type Description
data Any The parameter into which the message’s data payload is passed

agent.send()

Posts a message from the device to the agent

Availability

Device

Returns

Integer — 0 on success or a Send Error Code on failure

Parameters

Name Type Description
messageName String The name of the message
data Any The data to be passed to the agent

 

amqp

The agent-side object which represents the AMQP protocol

amqp.createbinarymessage()

Creates a new AMQP message in binary form

Availability

Agent

Returns

An amqpmessage object primed for transmission in binary form (‘AMQP DATA’)

Parameters

Name Type Description
body String The body of the message
properties Table Optional message properties as defined by the application

amqp.createmessage()

Creates a new AMQP message in UTF-8 form

Availability

Agent

Returns

An amqpmessage object primed for transmission in UTF-8 form (‘AMQP VALUE’)

Parameters

Name Type Description
body String The body of the message
properties Table Optional message properties as defined by the application

amqp.openconnection()

Initiates and manages a connection between the agent and a remote AMQP message broker

Availability

Agent

Returns

An amqpconnection object

Parameters

Name Type Description
url String The URL of the AMQP broker with which the connection will be established
eventCallback Function A function that will be called at key moments during the life of the object (see below).
It will be called with the following parameter(s):
Name Type Description
event String A constant representing the type of event that triggered the callback
errorDetail String or null In the event of an error, an error message string, otherwise null

 

amqpconnection

A manager for the connection to an AMQP broker

amqpconnection.close()

Instructs the target amqpconnection object to close

Availability

Agent

Returns

Nothing

Parameters

None

amqpconnection.isopen()

Indicates whether the target connection is open or closed

Availability

Agent

Returns

Boolean — true if the connection is open, otherwise false

Parameters

None

amqpconnection.opensession()

Attempts to open a new AMQP messaging session

Availability

Agent

Returns

An amqpsession object

Parameters

Name Type Description
eventCallback Function An optional function that will be called at key moments during the life of the object (see below).
It will be called with the following parameter(s):
Name Type Description
event String A constant representing the type of event that triggered the callback
errorDetail String or null In the event of an error, an error message string, otherwise null

 

amqpdelivery

The entity used to retrieve a message and to settle its delivery with the broker.

amqpdelivery.accept()

Informs the AMQP broker you have accepted the amqpdelivery’s message

Availability

Agent

Returns

Nothing

Parameters

None

amqpdelivery.message()

Returns the received message

Availability

Agent

Returns

The message as an amqpmessage object

Parameters

None

amqpdelivery.reject()

Informs the AMQP broker you have rejected the amqpdelivery’s message

Availability

Agent

Returns

Nothing

Parameters

None

amqpdelivery.release()

Releases the amqpdelivery’s message

Availability

Agent

Returns

Nothing

Parameters

None

 

amqpmessage

The agent-side object which represents an AMQP message

amqpmessage.body()

Returns the target AMQP message’s body content

Availability

Agent

Returns

Various — see below

Parameters

None

amqpmessage.properties()

Returns the target AMQP message’s properties

Availability

Agent

Returns

Table — the application-specific message properties

Parameters

None

 

amqpreceiver

An object which manages the reception of AMQP messages

amqpreceiver.close()

Instructs the target amqpreceiver object to close

Availability

Agent

Returns

Nothing

Parameters

None

amqpreceiver.isopen()

Indicates whether the target receiver is open or closed

Availability

Agent

Returns

Boolean — true if the amqpreceiver is open, otherwise false

Parameters

None

 

amqpsender

An object which manages the sending of AMQP messages

amqpsender.close()

Instructs the target amqpsender object to close

Availability

Agent

Returns

Nothing

Parameters

None

amqpsender.createtransfer()

Establish a single transfer to transport an outgoing AMQP message

Availability

Agent

Returns

An amqptransfer object

Parameters

Name Type Description
message An amqpmessage object The AMQP message to be sent

amqpsender.isopen()

Indicates whether the target sender is open or closed

Availability

Agent

Returns

Boolean — true if the sender is open, otherwise false

Parameters

None

 

amqpsession

Represents a communication session with an AMQP broker

amqpsession.close()

Instructs the target amqpsession object to close

Availability

Agent

Returns

Nothing

Parameters

None

amqpsession.isopen()

Indicates whether the target session is open or closed

Availability

Agent

Returns

Boolean — true if the session is open, otherwise false

Parameters

None

amqpsession.openreceiver()

Establishes a means to receive AMQP messages

Availability

Agent

Returns

An amqpreceiver object

Parameters

Name Type Description
path String The path of the target endpoint relative to the host
eventCallback Function An optional function that will be called at key moments during the life of the object (see below).
It will be called with the following parameter(s):
Name Type Description
event String A constant representing the type of event that triggered the callback
errorDetail String or null In the event of an error, an error message string, otherwise null
messageCallback Function A function that will be called when a message is received.
It will be called with the following parameter(s):
Name Type Description
deliveries An array of amqpdelivery objects (see below) A set of objects used to retrieve and settle messages

amqpsession.opensender()

Establishes a means to send AMQP messages

Availability

Agent

Returns

An amqpsender object

Parameters

Name Type Description
path String The path of the target endpoint relative to the host
eventCallback Function An optional function that will be called at key moments during the life of the object (see below).
It will be called with the following parameter(s):
Name Type Description
event String A constant representing the type of event that triggered the callback
errorDetail String or null In the event of an error, an error message string, otherwise null

 

amqptransfer

An object which manages the transfer of a single AMQP message

amqptransfer.cancel()

Cancel the AMQP transfer

Availability

Agent

Returns

Nothing

Parameters

None

amqptransfer.sendasync()

Send a specific AMQP message asynchronously

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
onSentCallback Function A function that will be called when the message has been sent

 

crypto

A device-side object which can be used to perform various hash functions

crypto.equals()

Compares two hashes for equality in constant time

Availability

Device (from impOS™ 36)

Returns

Bool — true if the hashes are equal, false otherwise

Parameters

Name Type Description
hashOne String or blob First comparison hash
hashTwo String or blob Second comparison hash

crypto.hmacsha256()

Performs an HMAC-SHA-256 hash function

Availability

Device (from impOS™ 36)

Returns

Blob — the hashed data (32 bytes)

Parameters

Name Type Description
dataToHash String or blob The data to which the hash function will be applied
key String or blob The hash key

crypto.sha256()

Performs an SHA-256 hash function

Availability

Device (from impOS™ 36)

Returns

Blob — the hashed data (32 bytes)

Parameters

Name Type Description
dataToHash String or blob The data to which the hash function will be applied

 

device

An agent-side object that represents the imp-enabled device to which that agent has been paired

device.info()

Obtain network and connection information about an agent’s paired device

Availability

Agent

Returns

A table of device information

Parameters

None

device.isconnected()

Indicates whether the device is currently connected to the server or not

Availability

Agent

Returns

Bool — true if the device is connected or false if it is not

Parameters

None

device.on()

Registers a function to process messages sent from the device to the agent

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
messageName String The name of the message with which the handler will be associated
callback Function The function that will be called when the named message is received.
It will be called with the following parameter(s):
Name Type Description
data Any The parameter into which the message’s data payload is passed

device.onconnect()

Registers a function that will be called when the device connects to the agent

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
callback Function The function that will be called automatically when the imp-enabled device connects

device.ondisconnect()

Registers a function that will be called when the device disconnects from the agent

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
callback Function The function that will be called automatically when the imp-enabled device disconnects
It will be called with the following parameter(s):
Name Type Description
reserved None See ‘Description’, below

device.send()

Posts a message from the agent to the device

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
messageName String The name of the message
data Any The data to be passed to the agent

 

fixedfrequencydac

An object that represents an imp’s 12-bit fixed-frequency DAC

fixedfrequencydac.addbuffer()

Queues a fresh buffer for consumption by the DAC

Availability

Device

Returns

Nothing

Parameters

Name Type Description
newBuffer Blob The buffer to queue

fixedfrequencydac.configure()

Configures the fixed-frequency DAC for use

Availability

Device

Returns

Nothing

Parameters

Name Type Description
pin pin object Any imp pin which supports DAC operation
sampleRate Float or Integer The sample rate in Hertz
buffers Array An array of up to eight non-zero blobs to be used as buffers of output data to output
callback Function The function that will be called when a buffer has been consumed (see below).
It will be called with the following parameter(s):
Name Type Description
buffer Blob The buffer most recently consumed by the DAC
flags Constant Optional processing flags: A_LAW_DECOMPRESS, AUDIO

fixedfrequencydac.start()

Starts the fixed-frequency DAC

Availability

Device

Returns

Nothing

Parameters

None

fixedfrequencydac.stop()

Stops the fixed-frequency DAC

Availability

Device

Returns

Nothing

Parameters

Name Type Description
flag Constant An optional processing flag, SYNC

 

ftp

A class which can be used to mediate FTP transfers

ftp.get()

Creates a new FTP download request object

Availability

Agent

Returns

httprequest object

Parameters

Name Type Description
URL String The URL from which to retrieve the file or directory listing

ftp.put()

Creates a new FTP upload request object

Availability

Agent

Returns

httprequest object

Parameters

Name Type Description
URL String The URL to which the body will be uploaded
body Blob or String The data to upload

 

hardware

A device-only object that represents the device’s IO peripherals.

hardware.getdeviceid()

Returns the device’s unique ID code

Availability

Device (from impOS™ 27)

Returns

String — the device’s ID code

Parameters

None

hardware.lightlevel()

Returns a reading from the imp’s light-level sensor

Availability

Device (from impOS™ 27)

Returns

Integer — the 16-bit photosensor reading

Parameters

None

hardware.micros()

Returns the current value of the imp’s free-running microsecond timer

Availability

Device

Returns

Integer — the number of microseconds counted

Parameters

None

hardware.millis()

Returns the current value of the imp’s free-running millisecond timer

Availability

Device

Returns

Integer — the number of milliseconds counted

Parameters

None

hardware.vbat()

Returns the true battery voltage of imp003-based devices

Availability

Device (from impOS™ 32)

Returns

Float — the actual battery voltage (VBAT)

Parameters

None

hardware.voltage()

Returns the imp power supply voltage

Availability

Device

Returns

Float — the analog supply voltage

Parameters

None

hardware.wakereason()

Returns a constant indicating the reason why the imp was woken

Availability

Device

Returns

Integer — the Wake-up Code

Parameters

None

 

hash

A class which can be used to perform various hash functions

hash.hmacsha1()

Performs an HMAC-SHA1 hash function

Availability

Agent

Returns

Blob — the hashed data (20 bytes)

Parameters

Name Type Description
dataToHash String or blob The data to which the hash function will be applied
key String or blob The hash key

hash.hmacsha256()

Performs an HMAC-SHA-256 hash function

Availability

Agent

Returns

Blob — the hashed data (32 bytes)

Parameters

Name Type Description
dataToHash String or blob The data to which the hash function will be applied
key String or blob The hash key

hash.hmacsha512()

Performs an HMAC-SHA-512 hash function

Availability

Agent

Returns

Blob — the hashed data (64 bytes)

Parameters

Name Type Description
dataToHash String or blob The data to which the hash function will be applied
key String or blob The hash key

hash.md5()

Performs an MD5 hash function

Availability

Agent

Returns

Blob — the hashed data (16 bytes)

Parameters

Name Type Description
dataToHash String or blob The data to which the hash function will be applied

hash.sha1()

Performs an SHA-1 hash function

Availability

Agent

Returns

Blob — the hashed data (20 bytes)

Parameters

Name Type Description
dataToHash String or blob The data to which the hash function will be applied

hash.sha256()

Performs an SHA-256 hash function

Availability

Agent

Returns

Blob — the hashed data (32 bytes)

Parameters

Name Type Description
dataToHash String or blob The data to which the hash function will be applied

hash.sha512()

Performs an SHA-512 hash function

Availability

Agent

Returns

Blob — the hashed data (64 bytes)

Parameters

Name Type Description
dataToHash String or blob The data to which the hash function will be applied

 

http

A class which provides methods that can be used to mediate HTTP and other Internet messaging

http.agenturl()

Returns the agent’s unique URL

Availability

Agent

Returns

String — the agent’s full URL

Parameters

None

http.base64decode()

Decodes a base64-encoded string or blob

Availability

Agent

Returns

Blob — the decoded bytes, or a zero-length blob if the data is not valid Base64

Parameters

Name Type Description
dataToDecode String or blob Base64 encoded data

http.base64encode()

Encodes a string or blob in Base64 format

Availability

Agent

Returns

String — the Base64-encoded data

Parameters

Name Type Description
dataToEncode String or blob The data you wish to encode

http.get()

Returns a new HTTP GET request object

Availability

Agent

Returns

httprequest object

Parameters

Name Type Description
URL String The URL to which the HTTP request will be made
headers Table Optional table of additional HTTP headers

http.httpdelete()

Returns a new HTTP DELETE request object

Availability

Agent

Returns

httprequest object

Parameters

Name Type Description
URL String The URL to which the HTTP request will be made
headers Table Optional table of additional HTTP headers

http.jsondecode()

Parses JSON data into objects

Availability

Agent

Returns

Almost anything (see ‘Description’, below)

Parameters

Name Type Description
JSONstring String A valid JSON string

http.jsonencode()

Encodes a Squirrel object into JSON data

Availability

Agent

Returns

String — the JSON data

Parameters

Name Type Description
value Null, boolean, integer, float, string, array or table The object to encode

http.onrequest()

Registers a function to be executed on receipt of an incoming HTTP request

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
callback Function An HTTP request handler callback (see below).
It will be called with the following parameter(s):
Name Type Description
request Table The incoming HTTP request decoded into key-value pairs
response An httpresponse object An automatically generated HTTP response for replying to the source of the request

http.post()

Returns a new HTTP POST request object

Availability

Agent

Returns

httprequest object

Parameters

Name Type Description
URL String The URL to which the HTTP request will be made
headers Table Optional table of additional HTTP headers
body String The body of the HTTP request

http.poststream()

Returns a new HTTP POST stream request object

Availability

Agent

Returns

An httpstream object primed to make a POST request

Parameters

Name Type Description
url String The URL to which the stream will be sent
headers Table A table of additional HTTP headers (may be empty)
callback Function A function that will be executed when the transfer completes either successfully or because of an error.
It will be called with the following parameter(s):
Name Type Description
response Table The returned response decoded into key-value pairs

http.put()

Returns a new HTTP PUT request object

Availability

Agent

Returns

httprequest object

Parameters

Name Type Description
URL String The URL to which the HTTP request will be made
headers Table Optional table of additional HTTP headers
body String The body of the HTTP request

http.putstream()

Returns a new HTTP PUT stream request object

Availability

Agent

Returns

An httpstream object primed to make a PUT request

Parameters

Name Type Description
url String The URL to which the stream will be sent
headers Table A table of additional HTTP headers (may be empty)
callback Function A function that will be executed when the transfer completes either successfully or because of an error.
It will be called with the following parameter(s):
Name Type Description
response Table The returned response decoded into key-value pairs

http.request()

Returns a new generic HTTP request object

Availability

Agent

Returns

httprequest object

Parameters

Name Type Description
method String The HTTP method (verb) required (eg. HEAD, OPTIONS etc.)
URL String The URL to which the HTTP request will be made
headers Table Optional table of additional HTTP headers
body String The body of the HTTP request, or an empty string

http.requeststream()

Returns a new HTTP stream request object

Availability

Agent

Returns

An httpstream object

Parameters

Name Type Description
verb String The HTTP method required (eg. HEAD, OPTIONS etc.)
url String The URL to which the stream will be sent
headers Table A table of additional HTTP headers (may be empty)
callback Function A function that will be executed when the transfer completes either successfully or because of an error.
It will be called with the following parameter(s):
Name Type Description
response Table The returned response decoded into key-value pairs

http.urldecode()

Parses a string containing URL-encoded key-value pairs

Availability

Agent

Returns

Table — the URL-encoded data as key-value pairs

Parameters

Name Type Description
URLdataString String The URL-encoded string you wish to decode

http.urlencode()

Encodes a table of key-value pairs into a single URL-encoded string

Availability

Agent

Returns

String — the URL-encoded data

Parameters

Name Type Description
dataTable Table The key-value pair(s) to be encoded

 

httprequest

A class which represents a single HTTP transaction

httprequest.cancel()

Cancels an HTTP request sent asynchronously

Availability

Agent

Returns

Nothing

Parameters

None

httprequest.sendasync()

Issues the target HTTP request and registers functions to be executed asynchronously when the HTTP transaction completes

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
doneCallback Function A function that will be executed upon completion of the request.
It will be called with the following parameter(s):
Name Type Description
response Table The returned response decoded into key-value pairs
streamCallback Function Optional second handler function for streaming requests.
It will be called with the following parameter(s):
Name Type Description
content String The content from the stream
timeout Float or integer Optional timeout in seconds for streaming requests

httprequest.sendsync()

Issues the target HTTP request and pauses program execution until the transaction completes

Availability

Agent

Returns

Table — the decoded response from the remote server

Parameters

None

httprequest.setvalidation()

Sets the validation option for Secure HTTP (HTTPS) communications

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
validation Constant Validation option (see ‘Description’, below)

 

httpresponse

An object which represents the agent’s response to a single incoming HTTP request

httpresponse.header()

Adds an HTTP header to the response object

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
headerName String The header’s name (key) without the colon (":")
headerValue String The header’s value

httpresponse.send()

Issues the response to an incoming HTTP request

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
statusCode Integer A valid HTTP status code
responseBody String The response body, if any

 

httpstream

A class which represents a single HTTP streaming transaction

httpstream.cancel()

Cancel and close an HTTP stream

Availability

Agent

Returns

Nothing

Parameters

None

httpstream.closeasync()

Close an asynchronous HTTP stream

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
callback Function Optional second handler function for streaming responses.
It will be called with the following parameter(s):
Name Type Description
content String The content from the stream
timeout Float or integer Optional timeout in seconds

httpstream.closesync()

Close a synchronous HTTP stream

Availability

Agent

Returns

Table — the decoded response from the remote server

Parameters

None

httpstream.send()

Sends data via an outbound HTTP stream

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
data String or blob The data to be streamed

httpstream.setvalidation()

Sets the validation option for Secure HTTP (HTTPS) communications

Availability

Agent

Returns

Nothing

Parameters

Name Type Description
validation Constant Validation option (see ‘Description’, below)

 

I2C

A class which represents imp I²C two-wire serial ports

i2c.configure()

Configures the I²C clock speed and enables the port

Availability

Device

Returns

Nothing

Parameters

Name Type Description
clockSpeed Constant The preferred I²C clock speed

i2c.disable()

Disables the I²C bus

Availability

Device (from impOS™ 30)

Returns

Nothing

Parameters

None

i2c.read()

Initiates an I²C read from a specific register within a specific device

Availability

Device

Returns

String — the characters read from the I²C bus, or null on error

Parameters

Name Type Description
deviceAddress Integer The 8-bit I²C base address
registerAddress String The I²C sub-address, or "" for none
numberOfBytes Integer The number of bytes to read from the bus

i2c.readerror()

Returns the error code generated by the last I²C read

Availability

Device (from impOS™ 30)

Returns

Integer — an I²C Error Code, or the constant NO_ERROR

Parameters

None

i2c.write()

Initiates an I²C write to the device at the specified address

Availability

Device

Returns

Integer — 0 for success, or an I²C Error Code

Parameters

Name Type Description
deviceAddress Integer The 8-bit I²C base address
registerPlusData String The I²C sub-address and data, or "" for none

 

imp

An automatically instantiated object which provides methods that control and yield information about the imp.

imp.cancelwakeup()

Cancels a timer previously established by imp.wakeup()

Availability

Device (from impOS™ 27), agent

Returns

Nothing

Parameters

Name Type Description
timer Timer object A timer object as returned by imp.wakeup()

imp.clearconfiguration()

Erases the network settings and credentials held by a device

Availability

Device

Returns

Nothing

Parameters

Name Type Description
action Constant A value specifying the clearing action to be performed. Default: all (from release 33)

imp.configparams

A table of information relevant to imp factory configuration

Availability

Device, agent

Type

Table

imp.deepsleepfor()

Disconnects the imp from WiFi and puts it into deep sleep for the specified period

Availability

Device

Returns

Nothing

Parameters

Name Type Description
sleepTime Integer The deep sleep duration in seconds (0—2419198)

imp.deepsleepuntil()

Disconnects the imp from WiFi and puts it into deep sleep until the specified time

Availability

Device

Returns

Nothing

Parameters

Name Type Description
hour Integer The wake-up hour in 24-hour format (midnight = 0)
minute Integer The wake-up minute (0—60)
second Integer Optional, the wake-up second (0—60, default = 0)
day Integer Optional, the day of week on which to wake (0—6, default = any)

imp.enableblinkup()

Enables or disables BlinkUp™ on a device

Availability

Device

Returns

Nothing

Parameters

Name Type Description
enable Bool Whether BlinkUp configuration should be enabled (true) or disabled (false)

imp.environment()

Returns information about the imp’s type

Availability

Device, agent

Returns

Integer — the value of the imp’s environment constant

Parameters

None

imp.getbootromversion()

Returns the current version of the imp’s BootROM

Availability

Device (from impOS™ 32)

Returns

String — the special version string of the imp’s BootROM firmware

Parameters

None

imp.getcountry()

Returns the imp’s specified WiFi regulatory territory

Availability

Device (from impOS™ 30)

Returns

A string constant indicating the imp’s set region

Parameters

None

imp.getmemoryfree()

Returns the amount of currently unused memory in the imp

Availability

Device, agent

Returns

Integer — the amount of available RAM in bytes

Parameters

None

imp.getpoweren()

Returns the current state of certain imps’ POWER_EN pin

Availability

Device (from impOS™ 27)

Returns

Bool — true if POWER_EN is set, otherwise false

Parameters

None

imp.getpowersave()

Returns the imp’s current WiFi power-save setting

Availability

Device

Returns

Bool — true if WiFi power-save mode is active, otherwise false

Parameters

None

imp.getsoftwareversion()

Returns the imp or agent’s firmware version as a string

Availability

Device, agent

Returns

String — impOS™ version information

Parameters

None

imp.getuserconfiguration()

Retrieves stored device-level persistent user data

Availability

Device (from impOS™ 36)

Returns

The stored user data as a blob

Parameters

None

imp.info()

Returns information about the imp on which your code is running

Availability

Device (from impOS™ 36)

Returns

Device information (see below)

Parameters

None

imp.onidle()

Registers a function to be executed when the imp next goes idle

Availability

Device

Returns

Nothing

Parameters

Name Type Description
callback function The function to call when the imp goes idle.
The function has no parameters

imp.onunhandledexception()

Register a global error handler

Availability

Device (from impOS™ 38)

Returns

Nothing

Parameters

Name Type Description
errorHandler Function The function called when an untrapped error occurs

imp.scanwifinetworks()

Returns a list of WiFi networks detectable by the imp

Availability

Device (from impOS™ 27)

Returns

Array — a list of nearby WiFi networks, each detailed in a table

Parameters

Name Type Description
callback Function Optional single-parameter callback to be executed when the scan is complete (from impOS™ 36)

imp.setcountry()

Specifies the imp’s WiFi regulatory territory at blessing

Availability

Device (from impOS™ 30)
Available for use in Factory Firmware only

Returns

Nothing

Parameters

Name Type Description
regionCode Integer A constant specifying the device’s usage region

imp.setenroltokens()

Installs Electric Imp impCloud™ enrolment tokens into the imp

Availability

Device (from impOS™ 30)

Returns

Nothing

Parameters

Name Type Description
planID String The plan ID for the enrollment
token String The enrollment token itself

imp.setnvramimage()

Sets the NVRAM image of certain imps at blessing

Availability

Device (from impOS™ 30)
Available for use in Factory Firmware only

Returns

A hash of the NVRAM image as a string

Parameters

Name Type Description
settings String The imp003 or imp005’s WiFi controller settings

imp.setpoweren()

Attempts to change the state of certain imps’ POWER_EN pin

Availability

Device (from impOS™ 27)

Returns

Nothing

Parameters

Name Type Description
state Bool Whether to enable (true) or disable (false) POWER_EN

imp.setpowersave()

Enables or disables the imp WiFi sub-system’s power-save mode

Availability

Device

Returns

Nothing

Parameters

Name Type Description
state Bool Whether to enable (true) or disable (false) power-save mode

imp.setproxy()

Configures the device for Internet access through a proxy server

Availability

Device (from impOS™ 33)

Returns

Nothing

Parameters

Name Type Description
proxyType Constant Currently must be set to PROXY_TYPE_HTTP
address String The proxy server address in dotted quad or a resolvable form,
eg. "192.168.0.128" or "proxy.electricimp.com". Up to 64 characters in length.
port Integer Port number between 0 and 65535
username String Optional, the server login username. Up to 32 characters in length
password String The server login password, only required when the username parameter is used.
Up to 32 characters in length

imp.setrescuepin()

Configures a rescue pin

Availability

Device (from impOS™ 36)
Available for use in Factory Firmware only

Returns

Nothing

Parameters

Name Type Description
pin An imp pin object The assigned rescue pin, or null to clear the setting
polarity Integer 1 for Logic High, 0 for Logic Low

imp.setsendbuffersize()

Attempts to set the size of the imp’s TCP send window for server communications

Availability

Device (from impOS™ 27)

Returns

Integer — the previous size of the imp’s TCP send window in bytes

Parameters

Name Type Description
newSize Integer The requested TCP send window size in bytes

imp.setstaticnetworkconfiguration()

Allows a static network configuration to be applied to the device

Availability

Device (from impOS™ 33)

Returns

Nothing

Parameters

Name Type Description
ip String The desired static IPv4 address, eg. "192.168.0.128"
netmask String The network’s IPv4 address mask, eg. "255.255.255.0"
gateway String The network gateway’s IPv4 address, eg. "192.168.0.0"
dns Array of Strings An array of one or two strings, each the IPv4 address of a DNS server

imp.setuserconfiguration()

Sets device-level persistent user data

Availability

Device (from impOS™ 36)

Returns

Nothing

Parameters

Name Type Description
userData Blob or string Your persisted data

imp.setwificonfiguration()

Sets an imp’s saved WiFi network access data

Availability

Device

Returns

Nothing

Parameters

Name Type Description
SSID String The name of the network you want the imp to connect to
password String The network password or an empty string (`""`) if there is no encryption

imp.sleep()

Causes the imp to halt code execution for a specified period

Availability

Device, agent

Returns

Nothing

Parameters

Name Type Description
sleepTime float The delay duration in seconds

imp.wakeup()

Sets a timer and registers a function which will be called when the timer fires

Availability

Device, agent

Returns

The new timer object or null on error

Parameters

Name Type Description
interval Float The length of time in seconds to elapse before the timer fires (0—10737418)
callback Function The function to call when the timer fires.
The function is called with no parameters

 

net

An automatically instantiated object which provides methods that yield information about the imp’s network options.

net.configurewps()

Initiates an attempt to request WiFi credentials from a router using WPS

Availability

Device (from impOS™ 36)

Returns

Nothing

Parameters

Name Type Description
pin String Optional WPS PIN as a string of eight base-10 digits

net.info()

Returns the imp’s stored network configuration information

Availability

Device (from impOS™ 33)

Returns

Table containing the network configuration information (see below)

Parameters

None

 

nv

A pre-formed table object which provides non-volatile data storage while the imp is in deep sleep

 

Pin

A class which represents one of the imp’s GPIO pins

pin.configure()

Configures one of the imp’s GPIO pins for a particular mode of operation

Availability

Device

Returns

Nothing

Parameters

Name Type Description
pinType Constant The chosen mode of pin operation
... Various Multiple parameters to further define pin behavior, based on pin type

pin.getdelay()

Returns the specified PTPG output pin’s current delay value

Availability

Device

Returns

Float — the PTPG delay in seconds

Parameters

None

pin.getperiod()

Returns the period of a pin in PWM or PTPG mode

Availability

Device

Returns

Float — the PTPG or PWM period in seconds

Parameters

None

pin.getsteps()

Returns the step-count of a pin in PWM mode

Availability

Device

Returns

Integer — the PWM step-count

Parameters

None

pin.read()

Reads the state of the specified pin

Availability

Device

Returns

Integer — the state of the specified pin (see ‘Description’, below)

Parameters

None

pin.write()

Sets the state of the specified pin

Availability

Device

Returns

Nothing

Parameters

Name Type Description
value Integer or float The new state value to be which the pin will be set

 

sampler

An object which represents an imp’s 12-bit ADC

sampler.configure()

Configures the ADC for use

Availability

Device

Returns

Nothing

Parameters

Name Type Description
pins pin object or
an array of pin objects
Any pin which supports ADC/analog in, or an array of such pins
sampleRate Float or integer The frequency at which the sampler is set (in Hz)
buffers Array Array of blobs (up to eight), each a buffer for sampled data.
The size of each blob must be a multiple of twice the number of supplied pins
callback Function A function to be called when a sample buffer is full (see below).
It will be called with the following parameter(s):
Name Type Description
buffer Blob The samples to be processed
byteCount Integer The number of bytes (not samples) valid in the blob
filters Constant Optional pre-processing filters (see below)

sampler.getsampleratehz()

Returns the ADC’s current sampling rate

Availability

Device (from impOS™ 27)

Returns

Float — the ADC’s sample rate in Hz

Parameters

None

sampler.reset()

Resets the ADC, freeing all sample buffers

Availability

Device (from impOS™ 27)

Returns

Nothing

Parameters

None

sampler.start()

Starts the ADC

Availability

Device

Returns

Nothing

Parameters

None

sampler.stop()

Stops the ADC and sends the current buffer to the callback for processing

Availability

Device

Returns

Nothing

Parameters

None

 

server

A class which provides methods for communicating with the Electric Imp impCloud™

server.bless()

Binds a production device to specified application firmware and registers a function to be executed when the blessing attempt completes

Availability

Device
Available for use in Factory Firmware only

Returns

Nothing

Parameters

Name Type Description
testSuccess Bool Whether the device has passed (true) or failed (false) your tests, and so whether it should be blessed
callback Function Function to be called on completion of the blessing process.
It will be called with the following parameter(s):
Name Type Description
blessSuccess Bool The result of blessing

server.connect()

Attempts to establish a connection between the device and the server

Availability

Device

Returns

Nothing

Parameters

Name Type Description
callback Function Function to be called when a connection has been made or failed.
Ignored when SUSPEND_ON_ERROR is in effect.
It will be called with the following parameter(s):
Name Type Description
reason Constant The result of the connection attempt
timeout Integer Optional time in seconds to wait for a connection to be made (default = 60).
Ignored when SUSPEND_ON_ERROR is in effect

server.disconnect()

Disconnects the devices from the server and turns WiFi off

Availability

Device

Returns

Nothing

Parameters

None

server.error()

Posts an error message to the server-hosted log and highlighted as such in the IDE

Availability

Device, agent

Returns

Integer — 0 on success, or a Send Error Code on failure

Parameters

Name Type Description
errorMessage String The error to be logged

server.factoryblinkup()

Triggers an imp to perform a BlinkUp operation on a second imp

Availability

Device
Available for use in Factory Firmware only

Returns

Nothing

Parameters

Name Type Description
SSID String The name of the factory WiFi network
password String The factory WiFi network’s password, or "" if no password is required
pin pin object The pin to which the BlinkUp transmission LED is attached
flags Integer Bitfield of BlinkUp flags (see below), or 0 if none needed

server.flush()

Suspends code execution until any pending data has been sent to the server

Availability

Device

Returns

Bool — true if the data has been sent, or false on any other outcome

Parameters

Name Type Description
timeout Float The maximum time in seconds to wait for pending data to be sent

server.isconnected()

Indicates to the device whether or not it is currently connected to the server

Availability

Device

Returns

Bool — true if the device is connected to the server, or false otherwise

Parameters

None

server.load()

Returns the most recent data stored using server.save()

Availability

Agent

Returns

Table — the data read from persistent storage

Parameters

None

server.log()

Adds a message to the server-hosted log, which is presented in the IDE

Availability

Device, agent

Returns

Integer — 0 on success, or a Send Error Code on failure

Parameters

Name Type Description
logEntry String The message to be logged

server.onshutdown()

Registers a function to be executed when the server requests a restart

Availability

Device

Returns

Nothing

Parameters

Name Type Description
callback Function A function with one parameter that will be executed when a restart is requested
It will be called with the following parameter(s):
Name Type Description
reason Integer A value indicating why the server has requested the restart

server.onunexpecteddisconnect()

Registers a function to be called if the imp unexpectedly disconnects from the server

Availability

Device

Returns

Nothing

Parameters

Name Type Description
callback Function A function to be called whenever the imp unexpectedly disconnects from the server.
It will be called with the following parameter(s):
Name Type Description
reason Integer The reason why the imp disconnected if known, otherwise NOT_CONNECTED

server.restart()

Manually restarts the device or agent

Availability

Device, agent

Returns

Does not return (see ‘Description’, below)

Parameters

None

server.save()

Stores data in server-side persistent storage

Availability

Agent

Returns

Integer — 0 on success, or a Send Error Code on failure

Parameters

Name Type Description
dataToSave Table The data you wish to preserve, placed in a table

server.setsendtimeoutpolicy()

Sets the device’s disconnection handling policy and its reconnection timeout period

Availability

Device

Returns

Nothing

Parameters

Name Type Description
onError Constant The disconnection handling policy: either SUSPEND_ON_ERROR or RETURN_ON_ERROR
waitFor Constant The successful transmission criterion: either WAIT_TIL_SENT or WAIT_FOR_ACK
timeout Float Maximum time (in seconds) allowed for the server to acknowledge receipt of data

server.sleepfor()

Disconnects from WiFi and puts the imp into a deep sleep state for the specified duration

Availability

Device

Returns

Does not return (see ‘Description’, below)

Parameters

Name Type Description
sleepTime Integer The deep sleep duration in seconds (0—2,419,198)

server.sleepuntil()

Disconnects from WiFi and puts the imp into a deep sleep state until a specified time

Availability

Device

Returns

Does not return (see ‘Description’, below)

Parameters

Name Type Description
hour Integer The wake-up hour in 24-hour format (midnight = 0)
minute Integer The wake-up minute (0—60)
second Integer Optional, the wake-up second (0—60, default = 0)
dayOfWeek Constant Optional, the day of week on which to wake (0—6, default = any)

 

SPI

A class which represents one of an imp’s SPI synchronous serial ports

spi.chipselect()

Controls the imp005’s dedicated SPI Chip Select pins

Availability

Device (from impOS™ 33)

Returns

Nothing

Parameters

Name Type Description
select Integer 1 to assert the dedicated chip select pin, or 0 to de-assert

spi.configure()

Configures the SPI data format and rate

Availability

Device

Returns

Integer — the actual SPI data rate in kHz

Parameters

Name Type Description
modeFlags Constant A bitfield comprising flags the specify the SPI configuration
dataRate Integer The SPI bus data transmission frequency in kHz

spi.disable()

Disables the specified SPI bus

Availability

Device (from impOS™ 30)

Returns

Nothing

Parameters

None

spi.readblob()

Reads data from SPI port and returns it as a series of bytes

Availability

Device

Returns

Blob — the bytes read from the SPI bus

Parameters

Name Type Description
numberOfBytes Integer How many bytes to read in from the bus

spi.readstring()

Reads data from the SPI port and returns it as a string

Availability

Device

Returns

String — the characters read from the SPI bus

Parameters

Name Type Description
numberOfChars Integer How many characters to read in from the bus

spi.write()

Sends data to the SPI port

Availability

Device

Returns

Integer — the number of bytes written to the SPI bus

Parameters

Name Type Description
data String or blob The data to write to the bus

spi.writeread()

Sends data to the SPI serial port and simultaneously reads the same amount of data

Availability

Device

Returns

String or blob — the data that was read during the write

Parameters

Name Type Description
data String or blob The data to write to the bus

 

spiflash

A class which represents SPI flash storage connected to an imp003 or later

spiflash.chipid()

Returns the identity code of the SPI flash chip

Availability

Device (from impOS™ 30)

Returns

Integer — the SPI flash chip’s standard ID code

Parameters

None

spiflash.disable()

Disables the SPI flash for reading and writing

Availability

Device (from impOS™ 30)

Returns

Nothing

Parameters

None

spiflash.enable()

Enables the SPI flash for reading and writing

Availability

Device (from impOS™ 30)

Returns

Nothing

Parameters

None

spiflash.erasesector()

Erases a 4KB sector of the SPI flash

Availability

Device (from impOS™ 30)

Returns

Nothing

Parameters

Name Type Description
sectorAddress Integer The address of the 4KB sector to be erased

spiflash.info()

Returns SPI flash User Info settings

Availability

Device (from impOS™ 33)

Returns

Table of SPI flash User Info settings

Parameters

None

spiflash.read()

Copies data from the SPI flash and returns it as a series of bytes

Availability

Device (from impOS™ 30)

Returns

Blob — the bytes read from the SPI flash

Parameters

Name Type Description
address Integer The address from which to copy the data
numberOfBytes Integer The number of bytes to copy

spiflash.readintoblob()

Copies data from the SPI flash storage into a pre-existing blob

Availability

Device (from impOS™ 30)

Returns

Nothing

Parameters

Name Type Description
address Integer Address from which to copy the data
targetBlob Blob The blob into which to copy the bytes
numberOfBytes Integer The number of bytes to copy

spiflash.setspeed()

Sets the speed of SPI flash accesses on imp003 and imp004m devices

Availability

Device (from impOS™ 34)

Returns

Integer — the actual speed of the SPI flash in Hertz

Parameters

Name Type Description
speed Float/Integer The requested SPI flash speed in Hertz

spiflash.size()

Returns the total number of bytes in the SPI flash that are available to Squirrel

Availability

Device (from impOS™ 30)

Returns

Integer — the number of bytes of storage in the SPI flash available for user code use

Parameters

None

spiflash.write()

Writes a full or partial blob into the SPI flash

Availability

Device (from impOS™ 30)

Returns

Integer — 0 if no write verification selected or verification was successful, otherwise a verification failure indicator

Parameters

Name Type Description
address Integer Address to write the data to
dataSource Blob The source blob from which to copy the data
writeFlags Constant Optional flags to select from pre- and post-verification of the write
startIndex Integer Optional location within the source blob at which reading starts
endIndex Integer Optional location within the source blob at which reading stops

 

UART

A class which represents one of an imp’s UART asynchronous serial ports

uart.configure()

Configures the UART serial bus

Availability

Device

Returns

Integer — the actual connection speed in bits per second

Parameters

Name Type Description
baudRate integer Baud rate (bits per second)
wordSize integer Word size in bits (7 or 8)
parity const Parity (constant, see below)
stopBits integer Stop bits (1 or 2)
flags const Control flags (bitfield constant, see below)
callback function Optional callback function for UART events. See ‘Callback Function’, below, for this function’s optional parameters (none by default)

uart.disable()

Disables the UART interface

Availability

Device

Returns

Nothing

Parameters

None

uart.flags()

Returns event flags set by the previous UART transaction

Availability

Device (from impOS™ 30)

Returns

Integer — the UART transaction event flags bitfield

Parameters

None

uart.flush()

Pauses program execution until the UART’s output FIFO has drained

Availability

Device

Returns

Nothing

Parameters

None

uart.read()

Reads a byte from the serial port

Availability

Device

Returns

Integer — the value read from the UART FIFO, or -1 if the FIFO is empty

Parameters

None

uart.readblob()

Reads a specified number of bytes from the serial port

Availability

Device (from impOS™ 30)

Returns

Blob — the bytes read from the UART FIFO, or a zero-length blob if the FIFO is empty

Parameters

Name Type Description
numberOfBytes integer Optional number of bytes to read (default = 80)

uart.readstring()

Reads a string of characters from the serial port

Availability

Device (from impOS™ 30)

Returns

String — the characters read from the UART FIFO, or an empty string if the FIFO is empty

Parameters

Name Type Description
numberOfChars integer Optional number of characters to read (default = 80)

uart.setrxfifosize()

Specifies the size of the UART receive FIFO

Availability

Device (from impOS™ 32)

Returns

Nothing

Parameters

Name Type Description
newInputFifoSize Integer The new size of the receive FIFO in bytes

uart.settxactive()

Configures a pin as a UART-transmit-active indicator

Availability

Device (from impOS™ 33.20)

Returns

Nothing

Parameters

Name Type Description
pin pin object The imp pin to be used to signal the UART TX state
polarity Integer 1 for active-high, 0 for active-low
predelay Integer Optional pre-delay in microseconds (default: 2)
postdelay Integer Optional post-delay in microseconds (default: 2)

uart.settxfifosize()

Sets the size of the UART transmit FIFO

Availability

Device (from impOS™ 32)

Returns

nothing

Parameters

Name Type Description
newOutputFifoSize Integer The new size of the transmit FIFO in bytes

uart.write()

Sends one or more bytes to the serial port

Availability

Device

Returns

Nothing

Parameters

Name Type Description
dataToWrite integer, string or blob One or more values to write to serial port

 

usb

An object which represents the imp005’s USB bus

usb.configure()

Configure the imp005’s USB

Availability

Device (from impOS™ 33)

Returns

Nothing

Parameters

Name Type Description
callback Function The function that will be called in response to a USB event.
It will be called with the following parameter(s):
Name Type Description
eventType Constant The type of event that triggered the callback
eventDetails Table Event-specific information

usb.controltransfer()

Initiates a control transfer via the imp005’s USB

Availability

Device (from impOS™ 33)

Returns

Nothing

Parameters

Name Type Description
speed Float The speed in Mb/s. Must be either 1.5 or 12
deviceAddress Integer The address of the device
endpointAddress Integer The address of the endpoint
requestType Integer (bitfield) The type of the endpoint
request Integer The specific USB request
value Integer A value determined by the specific USB request (range 0x0000-0xFFFF)
index Integer An index value determined by the specific USB request (range 0x0000-0xFFFF)
maxpacketsize Integer The maximum size of packet that can be written or read on this endpoint
data Blob Optional storage for incoming or outgoing data

usb.disable()

Disables the imp005’s USB

Availability

Device (from impOS™ 33)

Returns

Nothing

Parameters

None

usb.generaltransfer()

Initiates a transfer via the imp005’s USB

Availability

Device (from impOS™ 33)

Returns

Nothing

Parameters

Name Type Description
deviceAddress Integer The address of the device
endpointAddress Integer The address of the endpoint
type Integer The type of the endpoint
data Blob The data to be transferred

usb.openendpoint()

Opens the endpoint for reading or writing via the imp005’s USB

Availability

Device (from impOS™ 34)

Returns

 

Parameters

Name Type Description
speed Float The speed in Mb/s. Must be either 1.5 or 12
deviceAddress Integer The address of the device
interface Integer The endpoint’s interface number
type Integer The type of the endpoint
maxpacketsize Integer The maximum size of packet that can be written or read on this endpoint
endpointAddress Integer The address of the endpoint
interval Integer Interval for polling endpoint for data transfers. Valid range: 1—255 (from impOS 36)