server | Dev Center

server

Availability

Device

Description

The server object is a singleton which provides functionality for controlling and communicating with the Electric Imp impCloud™ server. It is instantiated automatically when the Squirrel virtual machine starts. A connection to the server is required for the device to communicate with its agent, but the server object does not refer to the agent itself, rather to the infrastructure which supports the agent. To interact with the agent specifically, use the agent object.

All methods that send data to the server return 0 on success, or a Send Error Code:

Error Code Constant	Value	Description
SEND_ERROR_NOT_CONNECTED	1	There is no connection to the server
SEND_ERROR_TIMEOUT	2	The timeout expired before all the data was sent to the server
SEND_ERROR_DISCONNECTED	3	The connection was disconnected before all data was sent to the server
SEND_ERROR_WOULDBLOCK	4	The data to be sent would not fit in the send buffer

The values assigned to the constants may change in a future impOS release.

For more information on managing planned disconnections and dealing with unexpected breaks in connectivity, please see How To Run An imp-enabled Device Offline.
For sample code that can be used to manage sudden losses of connectivity, see the imp API Cookbook recipe Handle Unexpected Device Disconnections.

Member Entities

The server object has the following member methods:

server.bless() — Binds a production device to application firmware

server.connect() — Attempts to establish a connection between the imp and the server

server.connectwith() — Attempt to connect to the impCloud using a specified network interface

server.disconnect() — Disconnects the imp from the server and turns the network interface off

server.error() — Posts an error message to the impCentral device log

server.factoryblinkup() — Triggers an imp to perform a BlinkUp operation on a second imp

server.flush() — Suspends code execution until any pending data has been sent to the server

server.isconnected() — Indicates to the imp whether or not it is currently connected to the server

server.load() — Returns the most recent data stored in the impCloud™

server.log() — Posts a message to the impCentral™ device log

server.onshutdown() — Registers a function to be executed when the server requests a restart

server.onunexpecteddisconnect() — Registers a function to be called if the imp unexpectedly disconnects from the server

server.restart() — Manually restarts the imp or its agent

server.save() — Preserves data in server-side persistent storage

server.setsendtimeoutpolicy() — Sets the device’s disconnection handling policy and its reconnection timeout period

server.sleepfor() — Puts the imp into a deep sleep state for the specified duration

server.sleepuntil() — Puts the imp into a deep sleep state until a specified time

The server object also has the following deprecated member methods, which should not be used in new code, but are documented here as an aid to understanding and migrating old code:

~~server.expectonlineat()~~ — Tells the server that the device will be disconnecting and that it will reconnect at a specified time

~~server.expectonlinein()~~ — Informs the server that the device will be disconnecting and that it will reconnect after a specified time

~~server.setpermanentvalues()~~ — No longer used data persistence method

~~server.show()~~ — Former logging method for Planner (superseded by the IDE and impCentral)

The server object also has the following deprecated member property, which should not be used in new code, but are documented here as an aid to understanding and migrating old code:

~~server.permanent()~~ — A table of permanent values passed between imp and agent at boot time