Devices

Part of the IP4CMS portal. ← All module guides

What it's for — The Devices module is your catalog of the physical devices installed across your properties — meters, sensors and similar equipment. You define reusable device types (the kind of device, plus the integration handler that talks to it), then register individual device instances and bind each one to a location. When a device is tied to a utility, it becomes a metering point: its readings flow into the utilities/metering data and it can surface to residents, while you run handler-provided actions (such as viewing usage) directly from the device.

Where to find it — Main navigation: Devices (route /app/devices). This opens All Devices, the list of every registered device instance. Click any row to open its detail page (/app/devices/:id). Device types are managed separately under Settings → Devices (/app/settings/devices), which has two sub-tabs: Device types and Instances.

Before you start

• The Devices licence module must be enabled for your tenant. If it isn't, the list shows "The devices module is not enabled for this tenant" and the nav item is hidden.
• You need device permissions (see Permissions & access). To browse devices you need devices:instances:read; to add or edit them you need devices:instances:write. Managing device types needs the devices:types:* permissions, normally exercised from Settings.
• To register an instance you first need at least one device type defined and at least one location to bind it to.
• The utility integration features (assigning a utility, choosing a provisioning channel, running actions) depend on the Utilities module also being enabled. Without it, the Utility and Provisioning channel fields don't appear.

Key tasks

Define a device type

Device types are the catalog templates that instances are created from. They live under Settings.

1. Go to Settings → Devices and select the Device types sub-tab.
2. Click Add Device Type (you need devices:types:create).
3. Fill in the fields:

• Name — display name shown in pickers and lists (e.g. "Electricity Meter"). Required.
• Code — a short internal code for the type. Required.
• Handler (handler_key) — the integration handler that drives this type's actions and provisioning. Defaults to stub. Set this to the handler key of the integration you're using; it determines which actions a device of this type advertises.

1. Save. The new type now appears in the type pickers when you register instances.

To change a type later, edit it from the same sub-tab (needs devices:types:update). You can update its name, handler and active status; a type can also be marked inactive so it stops appearing as a choice for new instances.

Register a device instance

This is the everyday task of recording a real device.

1. Open Devices from the main nav (or the Instances sub-tab in Settings).
2. Click Add device (you need devices:instances:write).
3. Complete the form:

• Device type (required) — pick from your defined types. If none exist you'll see "No device types defined" — define one first.
• Location (required) — the property/location the device is physically installed at. Only locations you can manage are selectable.
• Label — a friendly name, e.g. "Kitchen electricity meter". Optional but recommended; the list shows the label, falling back to the device ID if blank.
• Serial number — the device's serial/meter number, e.g. "SN-00482193". Used later to auto-match incoming meter readings.
• Utility (shown only when utility types exist) — choose the utility this device serves, or leave on "None — not a utility". When set, the device becomes a member-facing utility: it appears to residents who hold an approved claim on its property.
• Provisioning channel (shown only when channels exist) — leave on Auto to let the handler resolve from the device type + utility, or pick a specific channel to force its handler for this device.
• Provisioning configuration — if the chosen channel's handler advertises per-device fields, an extra section appears. These are per-device overrides; leave a field blank to use the channel default. (Secret fields are never shown here — device metadata is stored as plain data.)

1. Click Create device.

Bind or move a device to a location

Every device instance must be bound to exactly one location, set when you create it.

1. From All Devices, find the device and click Edit (or Open then edit).
2. Change the Location field to the new location. You can only move a device to a location you're allowed to manage.
3. Save. The move is validated against your tenant's locations; an invalid target is rejected.

You can also change the device's Status here — Active, Inactive or Decommissioned — along with its label, serial number, utility and channel.

Run a device action

Actions are operations exposed by the device's integration handler (for example, retrieving usage). What's available depends on the device's handler and its resolved utility channel.

1. From All Devices, click a row (or its Open button) to go to the device detail page.
2. The left panel shows Device details (type, serial, status, location link, device ID). The right panel is the actions panel.
3. The actions panel lists the actions the device currently supports:

• A usage action renders as an interactive usage chart, with selectable timeframes (24h, 7d, 30d, 90d, 1y), register and cumulative/delta views.
• Other action types show a card with their label and description.
• If nothing is available you'll see "No actions available — the integration for this device is not configured to expose any actions yet."

Actions are resolved in the device's live context. If the device or its provisioning channel can't be resolved, the panel reports an error you can retry.

Bulk-register devices

For large rollouts, register many instances at once instead of one by one.

1. On All Devices, click Bulk Upload.
2. Upload the device-instance file in the bulk-upload dialog. Each row maps to a device instance (it supports the same fields, including matching a device type and setting the utility type by name).
3. The upload runs in the background; you're notified when it starts processing, and the list refreshes.

Find and filter devices

The All Devices list supports quick narrowing:

• Search — type into the search box and press Enter to match by label, serial, type or location name.
• Add filter — filter by Location or Device type; active filters show as removable chips, and Clear all resets everything.

How the data connects

What you register → where it's stored

• A device type (device_type) holds the name, code and the integration handler_key. It's tenant-owned and reusable.
• A device instance (device_instance) is one physical device: it references its device type, is bound to a location_id, and carries an optional label, serial number, status, free-form metadata, an optional utility_type_id, and an optional provisioning_channel_id.

What it feeds

• Locations — every instance belongs to a location, so a property/location's detail view can list its devices and their actions. Access to a device is gated by access to its owning location.
• Utilities / metering — when an instance has a utility type set, it becomes a metering point. On create or update, the system runs a best-effort backfill that links any pending (unlinked) meter readings matching the device's serial/meter number and registers — so historical readings attach as soon as the device is told what utility it serves. The device then exposes utility actions (e.g. usage) and surfaces to residents with an approved claim at that location.
• Handlers / actions — the device type's handler (or an explicitly chosen provisioning channel's handler) decides which actions a device advertises. At the type level the action catalog is a static fallback; for a specific instance the actions are resolved dynamically against its active utility channel.

Permissions & access

The module is gated by the Devices licence module and by per-area permissions:

admin:full:access grants everything.

Location-scoped visibility. Operators who don't hold a device-admin permission only see and manage devices at locations they manage. The All Devices list is trimmed to their managed locations, and creating, opening or moving a device is blocked if they don't have access to the relevant location. Full device-admins see all devices across the tenant.

Tips & gotchas

• Two places, two jobs. The main Devices nav item is for instances (registering real devices). Settings → Devices is where device types are defined and is also where the instance list is mirrored. Define types before you try to add instances.
• Utility and channel fields are conditional. If you don't see Utility or Provisioning channel on the add/edit form, the Utilities module isn't enabled (or no utility types / active channels exist yet).
• Setting the utility unlocks resident visibility. Leaving Utility on "None" keeps the device internal. Setting it makes the device member-facing for residents with an approved claim — don't set it casually.
• Serial numbers matter for metering. The pending-readings backfill matches on serial/meter number. Register the correct serial up front (or it can be matched later when you edit and add the utility), or historical readings won't auto-link.
• Auto vs. explicit channel. Leaving the provisioning channel on Auto lets the platform resolve the handler from the device type and utility. Only pick an explicit channel when you need to override that resolution for one device.
• Provisioning config is per-device override, not the channel config. Fields in the Provisioning configuration section override the channel's defaults for this device only; blank = use the channel default. Secret fields are deliberately not editable here.
• Status is set on edit. The Status dropdown (Active / Inactive / Decommissioned) only appears when editing an existing device — new devices start as Active.
• Duplicate serials. The system treats a serial number as a near-unique key for lookups; having two active devices share one serial makes serial-based matching ambiguous, so keep serials unique.
• "Action preview not implemented." Some action render types don't yet have a built-in preview in the portal and show only a label/description card — this is expected, not an error.