Skip to main content

imp.configparams

A table of information relevant to factory configurations

Availability

Device + Agent

Returns

Table — keys differ between agent and device

Description

imp.configparams is a property of the global imp object. It is a table in which device and agent configuration details are stored. The table currently contains the following keys:

Device

Key Type Description
factoryfirmware Bool true if the device has been enrolled for factory use — it is a BlinkUp Fixture or a Device Under Test — or absent from the table
is_factory_fixture Bool true if the device is assigned to a Factory Device Group or Test Factory Device Group, or absent from the table
factory_imp_device_id String The device’s ID if it has been enrolled for factory use, or absent from the table.
Note The value provided by the DUT is its fixture’s device ID, not its own
factory_imp String The MAC address (lower-case, no punctuation) of the device if it has been enrolled for factory use, or absent from the table.
Note The value provided by the DUT is its fixture’s MAC, not its own

Agent

Key Type Description
factoryfirmware Bool true if the agent’s device has been enrolled for factory use, or absent from the table
is_factory_fixture Bool true if the agent’s device is assigned to a Factory Device Group or Test Factory Device Group, or absent from the table
factory_imp_device_id String The ID of the agent’s device if it has been enrolled for factory use, or absent from the table.
Note The value provided by the DUT’s agent is the ID of the DUT’s fixture, not its own
factory_fixture_url String The URL of the BlinkUp fixture that configured the agent’s device. This is available to the agents of DUTs only, it is absent otherwise
factory_imp String The MAC address (lower-case, no punctuation) of the agent’s device if it has been enrolled for factory use, or absent from the table.
Note The value provided by the DUT’s agent is the MAC of the DUT’s fixture, not its own
deviceid String The ID of the agent’s connected device, whether it is a factory device or not

Note Cellular-only imps have no MAC address, so factory_imp so this key will be absent on cellular fixtures and/or cellular DUTs.

Keys will be absent from imp.configparams tables when they are not relevant to the device or agent, so always check for aa key’s presence before taking action:

if ("factoryfirmware" in imp.configparams) {
    server.log("Running factory firmware");
}

When is imp.configparams Populated?

The contents of imp.configparams is populated during the imp’s communication with the impCloud™ during start-up. The table does not currently contain information that the imp itself ‘knows’; all of the information is supplied by the server. On a cold start, imp.configparams will be filled before Squirrel starts running. However, in the event of a warm boot, Squirrel starts immediately, and therefore it may be some time before imp.configparams is populated. Until this happens, imp.configparams contains no data.

Code which makes use of imp.configparams (see below) should ensure that under warm boot conditions the imp has opportunity to populate imp.configparams before it is read. This can be guaranteed by allowing the imp to go idle, ie. to reach a point where no Squirrel is running. The best way to do this is to embed your code in a function that will be called when the imp has gone idle:

imp.onidle(function() {
    if ("factoryfirmware" in imp.configparams) {
        server.log("Running factory firmware");
    }
});

The Role of imp.configparams

The table’s values are primarily intended to be used in factory firmware to help the code distinguish between the two types of factory device: BlinkUp fixtures, which are used to configure Devices Under Test (DUTs) with factory network access credentials, and the DUTs themselves. The same factory firmware runs on both of these types of device, for which it runs different code paths. It must distinguish between these devices in order to select the correct code path for the device on which it is running. This can be done using the following code snippet:

imp.onidle(function() {
    // imp.configparams will always be populated at this point
    if ("factoryfirmware" in imp.configparams) {
        // Value of imp.configparams.factoryfirmware doesn't matter, only its presence
        server.log("This device is running factory firmware...");

        if ("is_factory_fixture" in imp.configparams) {
            server.log("...and I am a BlinkUp fixture. Running the BlinkUp code path...");
            server.factoryblinkup(SSID, PASSWORD, pin, BLINKUP_FAST | BLINKUP_ACTIVEHIGH);
        } else {
            server.log ("...and I am a DUT. Running the test'n'bless path...");
            local success = performTests();
            if (success) {
                server.log("Tests passed; proceeding to bless DUT...");
                server.bless(success, postBlessCallback);
            } else {
                server.log("Tests failed.");
            }
        }
    } else {
        server.log("This device is not in an Electric Imp Connected Factory");
    }
});

Finally, imp.configparamsdeviceid key provides a way for an agent in day-to-day use to know the ID of the device it is bound to without having to ask the device:

local myDevId = imp.configparams.deviceid;