Skip to main content

impCentral System Variables

What development data is made available to your code

Electric Imp now provides a series of environmental constants which allow your Squirrel code to gather information about the impCentral entities of which it is a part: the Device Group it has been deployed to and the Product to which that Device Group belongs. Deployment details — D, SHA and creation date — are included too.

This information is accessible to code via the reserved identifier __EI, which is a Squirrel enum. You should ensure your code does not make use of such an identifier except for the purposes of accessing the impCentral data; if your code sets __EI, it will overwrite the auto-added values. Should further Electric Imp enumerations be added to code in the future, these too will be identifiable by a double-underscore prefix.

__EI has the following structure. Each property is a constant that is populated when Squirrel code is compiled before being sent to the agent server and to devices.

enum __EI { PRODUCT_ID = "...",
            PRODUCT_NAME = "...",
            DEVICEGROUP_ID = "...",
            DEVICEGROUP_NAME = "...",
            DEPLOYMENT_ID = "...",
            DEPLOYMENT_SHA = "...",
            DEPLOYMENT_CREATED_AT = "..." }

The value of each key is a string. Read a given property using dot syntax:

local myDevGrpID = __EI.DEVICEGROUP_ID;

The structure is automatically inserted into your code immediately prior to compilation, whether you upload your source to the impCloud™ using impCentral or a third-party tool based on the impCentral API. As such, the enumeration will not appear in your source code. Because the enumeration is a constant, the compiler will only add to the compiled code values which are explicitly referenced by your Squirrel. If you do not read any part of __EI, there will be no impact on your code size.

Example Code

The following code provides a function which can be added to development code to output useful information when the device restarts. In addition to network and impOS™ version information, the function uses __EI to add impCentral data to the readout.

function bootMessage() {
  // Present OS version and network connection information
  // Take the software version string and extract the version number
  local a = split(imp.getsoftwareversion(), "-");
  server.log("impOS version " + a[2]);

  // Get current networking information
  local i = imp.net.info();

  // Get the active network interface (or the first network on
  // the list if there is no network marked as active)
  local w = i.interface["active" in i ? i.active : 0];

  if (w != null) {
    // Get the SSID of the network the device is connected to
    // (or fallback to the last known network)
    local s = w.type == "wifi" ? ("connectedssid" in w ? w.connectedssid : ("ssid" in w ? w.ssid : "Unknown")) : "Unknown";

    // Get the type of network we are using (WiFi or Ethernet)
    local t = "Connected by " + (w.type == "wifi" ? "WiFi on SSID \"" + s + "\"" : "Ethernet");
    server.log(t + " with IP address " + i.ipv4.address);
  }

  // Present impCentral data
  server.log(format("Code SHA %s created at %s", __EI.DEPLOYMENT_SHA, __EI.DEPLOYMENT_CREATED_AT));
  server.log(format("Deployed to Device Group \"%s\" (ID: %s)", __EI.DEVICEGROUP_NAME, __EI.DEVICEGROUP_ID));
  server.log(format("Product \'%s\'", __EI.PRODUCT_NAME));
}

// Present device information now
bootMessage();

Squirrel code can also use the data to perform logic. For example, production code might read the name of the Production Device Group to which the device on which it is running has been assigned, and parse that name to perform different configuration flows accordingly:

local devGrp = __EI.DEVICEGROUP_NAME;

// Get country code from the last two chars of the device group name,
// eg. "CONNECTED_PRODUCT_SKU1234_US"
local country = devGrp.slice(devGrp.len() - 2);

// Set LCD UI language according to country
switch (country) {
  case "FR":
    setupForFrenchLanguage();
    break;

  case "DE":
    setupForGermanLanguage();
    break;

  case "IT":
    setupForItalianLanguage();
    break;

  case "CN":
    setupForChineseLanguage();
    break;

  default:
    setupForEnglishLanguage();
}