Skip to content
CC2 Device Documentation

Allocation & Return

The device can be allocated (assigned to a user) or unallocated (available for assignment). Allocation is normally managed through the Infrafon Entity Server (IES), but the device also supports local allocation and return for offline or testing scenarios.

IES allocation flow

Section titled “IES allocation flow”
  1. A kiosk or backend application calls the kmgr REST API to tell the IES that a user wants to allocate (or return) a device.
  2. The IES updates the device’s assignment state.
  3. The device checks with the IES whenever it goes on charge (to see if it has been returned) or off charge (to see if it has been allocated). This check is controlled by devcfg.core.iescheck (default true).
  4. If a transition is confirmed, the device downloads the new configuration (allocdata.json or unallocdata.json) and applies it.

Global dev and network config cannot be set through the kiosk allocate request. They always come from the entity, site, and dispenser configurations on the IES.

Local allocation / return

Section titled “Local allocation / return”

The device can also transition between states without contacting the IES, using devwork actions.

⚠ CRITICAL — the correct devwork envelope is:

{ "devwork": { "actions": [ ... ] } }

The bare array format ("devwork": [...]) is wrong and the device will ignore it.

Local allocate

Section titled “Local allocate”
{
  "devwork": {
    "actions": [
      { "a": "alloc_local" }
    ]
  }
}

Local return

Section titled “Local return”
{
  "devwork": {
    "actions": [
      { "a": "return_local" }
    ]
  }
}

These actions are useful for:

  • Testing allocation flows without an IES connection
  • Offline environments where the device is provisioned locally
  • Exiting provisioning mode (see Provisioning)

Setting user data in alloc_local

Section titled “Setting user data in alloc_local”

The alloc_local action accepts an optional user object that initialises application data after the state change.

{
  "devwork": {
    "actions": [
      {
        "a": "alloc_local",
        "p": {
          "user": {
            "user_name": "Jane Doe",
            "user_role": "Visitor"
          }
        }
      }
    ]
  }
}

Device View (DV) naming and source

Section titled “Device View (DV) naming and source”

When a device is allocated, the user.apps object in allocdata.json defines which DVs are active. Each DV has:

  • A source name – the key in user.apps (e.g. "badge_lock")
  • An id – the name the DV will use on the device (e.g. "lock")
  • A src – where the DV definition comes from
{
  "data": {
    "user": {
      "apps": {
        "badge_lock": {
          "id": "lock",
          "src": "local",
          "data": { "user_name": "John Doe" }
        }
      }
    }
  }
}

id – renaming DVs

Section titled “id – renaming DVs”

The id field allows you to use a different name on the IES and on the device. This is especially useful for built‑in DVs like "home" or "lock" that must have a specific name to be recognised by the device, but need unique names on the IES.

In the example above, the IES knows the DV as badge_lock, but the device loads it as lock.

src – DV origin

Section titled “src – DV origin”
ValueDescription
"inline"The DV definition is embedded in the allocdata JSON itself
"local"The DV definition is loaded from /dvs/<source name>.json
"https://…"The DV definition is fetched from a URL (not yet implemented)

HTTPS certificates

Section titled “HTTPS certificates”

HTTPS operations (allocation, return, DFU, widget actions) require the server’s CA certificate to be present on the device. Up to 10 certificates can be provisioned in /certs/ca/ and must be in DER format (file extension .der).

Only RSA signing is supported, with keys up to 4096 bits. Certificates are loaded once on the first HTTPS call. If they are updated, the device must be restarted.

Section titled “Related”