Working With The impC001

An Introduction To Electric Imp’s First Cellular Product

The impC001 is Electric Imp’s first cellular product, providing LTE connectivity as an alternative to the WiFi and Ethernet offered by other imps. The impC001 offers LTE category 1 support, in addition to either 2G or 3G fallback, and can make use of the current high-bandwidth LTE networks worldwide.

The impC001 has no internal WiFi radio, but it is capable of driving an external Ethernet RMII PHY and an external SDIO WiFi radio. However, support for Ethernet and WiFi is not yet present in impOS™.

While impOS currently features an integrated BLE stack, this is not yet included in the release version of the impOS for the impC001 but can be requested via support. This stack, along with additional BLE hardware, the impC001 will be able to provide BLE functionality (advertising, sniffing, GATT serving).


The impC001 module

The impC001 ships in a card form-factor compatible with NGFF M2 connectors.

This Guide will help you begin developing application code for the impC001. It covers the changes that have been made to the imp API to support cellular operation. Some previously deprecated imp API methods have been removed from the impC001’s build of impOS, and these are documented here to for customers who are looking to modify existing application code for the new platform.

Cellular communications introduces a number of behavioral changes to the imp’s established state diagram, and these are covered here too. In addition, this document provides guidance on those circumstances in which the impC001 may not behave the same as earlier imps because of, for example, the extra latency that cellular communications introduces.


The impC001 Breakout Board
 

For more information on the impC001 Breakout Board, please see the reference design page.

Activating The impC001

Cellular Network Access

Unlike other imp-based hardware, the impC001 connects to the Internet via LTE cellular networks. Each impC001 has an on-board, pre-activated eSIM with global roaming capabilities (limited by the bands supported by the actual cellular module on the impC001).

Cellular billing is automatic, and charged to the account holder's credit card monthly. All data allowances are pooled and roll over, simplifying budgeting significantly.

We expect customers to use the evaluation impC001 in their application in a similar manner to how they would use it in production, in order to get the most realistic usage data to inform development of the commercial module.

Device Activation

Development devices based on the impC001 are added to your Electric Imp account and impCentral™ in the usual way: with the Electric Imp mobile app (iOS or Android) and BlinkUp™.

BlinkUp Type

Please select Cellular as your connection method on the SETUP screen, and make sure you do not enable the Use advanced settings switch on the same screen.

Initial Connection

Typically, the impC001 will take 30 seconds or longer to boot the modem and connect to the cellular network (there is a 120-second timeout in place, see Connection Performance). If you are using the impC001 for the first time, or in a new country, it may take longer. The BlinkUp LED will stop flashing after 180 seconds which means status is not visible after this point.

Please be patient, especially on first connect, and allow the device several minutes for a first connection. If the first connection does not work, press the reset button on the impC001 Breakout Board and let the module try to connect again (the app will have timed out, but the device should still appear in impCentral when it is online).

If you cannot get the device to connect, try moving the device to an area with better signal.

BlinkUp Progress LED Patterns

The impC001’s BlinkUp LED status codes are similar to those on other imps, but include some special, cellular-specific patterns too.

Ready for activation  500ms 500ms Repeat
BlinkUp Successful  For three seconds
Waiting for modem  500ms 500ms 500ms 250ms Repeat
Waiting for SIM  500ms 500ms 500ms 250ms 500ms 250ms 500ms 250ms Repeat
Registering with a cell  500ms 500ms 500ms 250ms 250ms 250ms 500ms Repeat
Cell Registration Denied  500ms 500ms 500ms 500ms 500ms 500ms Repeat
Connecting via PPP  500ms 500ms 500ms 250ms Repeat
Checking PPP connection  500ms 500ms 500ms 250ms 250ms 250ms 250ms 250ms 500ms Repeat
Connected to server  500ms 500ms Repeat
Device lost connection  500ms 500ms Repeat
Device deliberately offline  500ms 250ms 250ms 250ms Repeat
Updating impOS™  Continuous for duration of update
Normal operation  LED not illuminated

Finding Your impC001-based Device In impCentral

When your impC001 connects successfully, it will be listed as an unassigned device in the Electric Imp’s online tool, impCentral, and you can assign it to a Product’s Development Device Group. To find the device, click impCentral’s Device icon (impCentral Devices Menu Icon) and then click My Development Devices. You can now assign the device to a Product/Development Device Group, and begin developing your application in the code editor.

Developing Applications With The impC001

This section provides technical guidance that will help you while you work with the impC001 and develop application code to run on it.

impC001 Identification

If you expect your code to run across multiple imp types and you need to choose code paths accordingly, call imp.info() — this returns a Squirrel meta object with the property type, which is is a string containing the imp module name:

if (imp.info().type == "impC001") {
    // Code running on impC001...
} else {
    // Code flow for other imps...
}

Cellular Band Support

Preliminary impC001 samples are available in three versions:

Variant LTE 3G Fallback 2G Fallback
impC001-eur Bands 1, 3, 8, 20, 28 UMTS bands 1, 8 900 and 1800MHz
impC001-us Bands 2, 4, 5, 12 UMTS bands 5, 4, 2 N/A
impC001-aus Bands 3, 5, 8, 28 UMTS bands 1, 5, 8 N/A

Both versions feature two u.FL antenna connectors: a primary antenna, which is used for transmit and receive, and an optional secondary antenna which can be used for RX diversity (LTE only).

imp API Methods Available To The impC001

The following imp API objects, classes and/or methods are currently implemented in the impC001 version of impOS:

imp API Methods That Are Not Yet Implemented

The following imp API objects, classes and/or methods are not implemented in release-40, but will be available in release-41 and later:

The following imp API objects, classes and/or methods are not expected to be implemented on the impC001:

The following imp API objects, classes and/or methods are not implemented in the impC001 version of impOS and, because they relate to WiFi usage, may not be added in future:

imp API Methods That Have Been Removed

We are discontinuing support for the following previously deprecated API methods. These calls will not be available to impC001-hosted code and will throw exceptions if included. If you are working to adapt existing code to the impC001, you will need to remove these calls. These methods will continue to be available on imp001 through imp005.

  • imp.configure()
  • imp.getssid()
  • imp.getbssid()
  • imp.getrssi()
  • imp.getchannel()
  • imp.getethernetspeed()
  • imp.getmacaddress()
  • imp.rssi()
  • spi.read(1)

Note Almost all of the network-related methods listed above can be replaced with imp.net.info(), which has been extended to support the impC001 (see below). The exception is imp.getmacaddress() as the impC001 MAC address is not provided by imp.net.info(). Currently, the only way to obtain the MAC address of an impC001 is to remove the 'c001' prefix from its device ID; what remains is the MAC address.

Getting Network Information

The imp API method imp.net.info() is the recommended means for acquiring network information from within Squirrel. The method returns network information as a table. One of this table’s keys is interface — its value is an array of one or more tables for each of the available network interfaces. In the case of the impC001, the interface array contains an entry which is a table with the following keys and values:

Key Type Notes
type String "cell"
manufacturer String The modem manufacturer, eg. "Cinterion"
model String The modem model number, eg. "ELS61-E"
imei String The imp’s International Mobile Equipment Identity number
imsi String The imp’s International Mobile Subscriber Identity number
swver String Modem software revision, eg. "REVISION 01.000"

In addition, the user can request information about the serving cell using the imp.net.cellinfo() API, which requests the information asynchronously.

For more information on the data contained in the cellinfo string, which varies according to the connected network type (2G, 3G, 4G etc), please see Cinterion ELS61-E AT Command Set, section 8.11.2.

Pin Mux

A list of the impC001’s GPIO pins and buses is available here.

Analog IO

All features, including sampler and fixed frequency DAC, are available on impC001.

UART

The UARTs provided by the impC001 initially have a minimum speed of 1526 baud and a theoretical maximum of 12.5 Mbaud.

USB host

The impC001 has a single USB bus accessed via pins A and B and controlled in Squirrel using hardware.usbAB.

Using Cellular Communications

In many respects, cellular communications are transparent to the application: you use the familiar imp API methods to communicate with the server and the device’s agent.

Connection Performance

Connecting to a cellular network takes longer than connecting to a WiFi network or via Ethernet. This is solely due to the nature of cellular networks, and is not something that can improved in hardware or software. To accommodate the increased connection time, and the latency of cellular connections, impOS’ key timeouts have been increased:

Timeout impC001 Value Notes
Cellular start-up timeout 120s Time allowed for the modem to power on and register on a network
Squirrel Hold Off 60s The time after which Squirrel will be started even if there is no connection yet
BlinkUp Status LED 180s The time after which BlinkUp will be disabled and the
Overall connect timeout 30s Time allowed from IP being available to the establishment of a server connection
DNS resolution retry interval 30s Time allowed for a DNS resolution retry if no response was received
Connect-or-snooze timeout 600s The SUSPEND_ON_ERROR send timeout policy
Upgrade network join and connect timeout 240s
Upgrade inactivity timeout 60s

Note These values do not apply to other imps (see Network State Diagram).

Connection Issues

The callback function(s) registered with server.connect() and/or server.onunexpecteddisconnect() will receive cellular-specific event notifications, where appropriate. The constants that may be passed into the callback as an integer are:

Constant Value Description
SERVER_CONNECTED 5 The server is connected
NOT_CONNECTED 0 The imp is not able to connect for a reason other than those listed below
NO_WIFI 1 Failed to join WiFi
NO_LINK 1 Failed to connect via Ethernet. imp005 only
NO_IP_ADDRESS 2 Failed to get an IP address
NOT_RESOLVED 3 The IP address of an Electric Imp server or proxy could not be resolved
NO_SERVER 4 Failed to connect to the Electric Imp server
NO_PROXY 6 The imp cannot connect via saved proxy address and port
NOT_AUTHORISED 7 The imp cannot connect because its proxy access credentials have been rejected
NO_MODEM 8 The imp cannot detect a modem. Cellular specific
SIM_ERROR 9 The imp cannot communicate with the modem’s SIM card. Cellular specific
NO_REGISTRATION 10 The imp could not detect a cellular network. Cellular specific
REGISTRATION_DENIED 11 The imp was not allowed to access the cellular network. Cellular specific
NO_PPP_CONNECTION 12 The imp could not establish a PPP connection. Cellular specific
PPP_NO_CONNECTIVITY 13 The imp could not establish an Internet connection. Cellular specific

The value passed into the callback can also be viewed by reading the table returned by imp.net.info(): check for the presence of the key lasterror; if present, its value will be one of the above integer constants:

if ("lasterror" in imp.net.info()) mySerialLogger.write(format("Could not connect; reason: %i", imp.net.info().lasterror));

Performance When Connected

Though LTE cat 1 is capable of 10Mbit/s down and 5Mbit/s up, all impC001 cellular communications go via PPP over USB. We have observed speeds of up to 1Mbit/s in both directions.

Power consumption

Preliminary measurements taken using the imp006-breakout rev 5.2, at the Li-Ion battery connector with a 3.7v logging supply:

  • Idle, connected to LTE: 40-50mA average
  • Idle, disconnected (UART configured): 9.5mA
  • Idle, disconnected (no UART configured): 1.4mA
  • Deep sleep: 95uA (the imp itself is ~8uA of this, the rest is the PMU, Gas gauge, etc)

Data Usage

impCellular™, Electric Imp’s commercial service package offered for cellular imps, provides 5MB of monthly data per device, pooled across all of your devices. All unused data rolls over to the following month. If you use data beyond the limit, it is billed at the rate of $0.05 per MB impCellular monthly fees are listed here.

A cellular imp’s data usage predominantly comprises messages moving back and forth between device and agent. If you wish to avoid extra data charges as described above, you should architect your cellular application to minimize device-agent traffic. It also includes device logging messages (see below) and application code sent to the device during deployments.

For example, there is a per-message 150-byte overhead in establishing a secure transfer between device and agent, in either direction. You should therefore try to aggregate messages wherever possible. Some applications simply pass one piece of data to the device or agent, such as a periodic sensor reading: consider batching these pieces as timestamped entries in an collection, and sending the batch after a certain period of time has elapsed or a certain number of messages are in the application's message pool. Contemporaneous readings from multiple sensors can similarly be aggregated into a single, timestamped message.

Example

function addData(reading) {
    local result = 0;

    // Add the new reading to the store
    dataArray.append(reading);

    // Is the store maxed out?
    if  (dataArray.len() == MAX_DATA_BEFORE_SEND) {
        result = agent.send("data.batch", { "timestamp" : time().
                                            "readings"  : dataArray });
    if (result == 0) {
            // Data sent OK, so begin storing again
            dataArray = [];
        } else {
            // Send failed for some reason (see agent.send() documentation
            // Remove oldest entry to make space for the next reading
            dataArray.remove(0);
        }
    }

    // Return the outcome of the operation (0 == success)
    return result;
}

Electric Imp’s free-to-use library, MessageManager, can assist you with integrating this methodology into your application.

You also also examine the data you are sending: do you need to provide readings as often as you do? Do you need to include as much information? If might be sufficient, for example, for your application to provide site environmental readings once an hour rather than every ten minutes.

Some messages of course need to be issued immediately: device-state alerts, for instance, and commands from the end-user. But it's possible to piggyback time-insensitive readings onto these time-sensitive messages.

impCentral™ provides a dashboard which displays a given Device Group’s data usage: either by the volume of data transferred (bytes) or the number of messages exchanged by Group’s devices and their agents. This data can help you understand your application's data usage and patterns of behavior.

Logging

The imp API’s logging methods, server.log() and server.error(), are throttled at the device level when called on Production Devices (ie. commercial units in the field), so these calls’ data transfers will not count toward a device’s data usage total unless logging is explicitly enabled for a given device for technical support or other maintenance purposes. Logs from a Production Device are automatically halted 24 hours after activation.

Moving To A Commercial Product

Moving from concept to a commercial product is easy: use our no-cost reference designs to create your customized product hardware with an M2 connector. The impC001 module can be ordered in volume by contacting us, and is PTCRB “end device” certified. It plugs into the M2 connector on your customized hardware, which also gives you the flexibility to configure your product with the upcoming lower-cost impC002 (LTE-Cat M/NB-IoT) unit.

For the development of your own proof-of-concept or prototype design, we have a pack of suitable M2 connectors and mounting posts available from the Electric Imp Store.

© 2024 KORE Wireless. All rights reserved. Terms of Service, Privacy Policy