Assets

The asset model is how Hiclaro represents every physical or logical thing in your environment — from a sensor on the wall to a person in the building.

What is an asset?

An asset is a persistent record in the Hiclaro database that represents something real — a device, a person, a vehicle, or a piece of equipment. Every plugin-managed IoT device becomes an asset the moment the plugin registers it. Users can also create assets manually for things that have no hardware integration, such as a resident of the building.

Assets are hierarchical: a child asset can belong to a parent asset via the parentId field. A sensor can belong to a hub, or a smart watch can belong to a person.

Asset classes

Every asset carries an assetClass that describes what kind of thing it is. Plugin-registered devices are always device. Other classes exist for non-device things you may want to model in your space.

Class	Intended use
`device`	Default. Any IoT hardware registered by a plugin — sensors, plugs, hubs, inverters.
`person`	A resident or occupant. Can be linked to a device (phone, watch) for automatic location tracking.
`vehicle`	A car, bike, or other vehicle. Supports GPS location via a tracker device.
`equipment`	Non-networked equipment you want to track — a generator, a tool, a piece of machinery.
`client`	A Hiclaro client app (desktop or mobile). Registered automatically when the app connects to the server.
`other`	Anything that doesn't fit the above categories.

Each asset also has a free-form assetType string for a more specific label — for example, a device asset might have assetType set to Plug, Hub, or Sensor.

Registering an asset from a plugin

Plugins register assets by publishing to the asset/updates MQTT topic. The payload wraps an event type and the asset data. The port field is the unique address — typically a MAC address, IP address, or serial port path — that identifies this asset across registrations. Hiclaro uses it to upsert: if an asset with that address already exists it is updated; otherwise a new one is created. Include pluginKey to associate the asset with the installing plugin — this links the asset to the plugin record so it can be filtered and managed together. Set configurable to true if the asset exposes plugin-managed configuration that the user can edit.

{
  "data": {
    "event": "assetAdded",
    "data": {
      "port": "AA:BB:CC:DD:EE:FF",
      "device_info": {
        "name": "Living Room Plug",
        "manufacturer": "TP-Link Systems Inc.",
        "device_type": "Plug"
      },
      "online": true,
      "configurable": true,
      "pluginKey": "tapo"
    }
  }
}

To mark an asset offline without removing it, publish an assetUpdated event with online: false:

{
  "data": {
    "event": "assetUpdated",
    "data": {
      "port": "AA:BB:CC:DD:EE:FF",
      "online": false
    }
  }
}

To remove an asset entirely, publish an assetRemoved event with the same port address. The asset record is soft-deleted and will no longer appear in the asset list.

See the full MQTT reference →

Publishing location

GPS-capable devices publish their position to the reserved asset/location topic. No datasource registration is needed — the platform handles this topic specially. The address field follows the same MAC/IP convention used in asset/updates.

{
  "address": "AA:BB:CC:DD:EE:FF",
  "lat": 47.5182,
  "lng": 19.0390,
  "altitude": 120
}

When a location message arrives, Hiclaro updates the asset's lat, lng, and altitude columns and re-evaluates which zone the asset is currently inside. If another asset has declared this asset as its locationSourceAssetId, its position is updated in the same step — for example, a person asset inheriting its location from a linked phone.

Full position history is stored as regular telemetry and is queryable via GET /telemetry using the system.location datasource for the asset in question.

Zone fields on assets

Each asset carries two independent zone fields that represent two different kinds of spatial information:

Field	Meaning	Updated by
`assignedZoneId`	Where the user declared this asset belongs — the living room, the garage, a particular floor. Never changed automatically.	User via `PATCH /assets/:id`
`currentZoneId`	The zone whose boundary polygon currently contains the asset's GPS fix. `null` if the asset is outside all zones or has no GPS data.	Platform — updated automatically on each location publish

A wall-mounted sensor will typically have assignedZoneId set once and currentZoneId remain null forever — it has no GPS. A person asset with a linked phone will have both fields updating independently: the user's declared home base stays in assignedZoneId while currentZoneId reflects where they actually are right now.

Learn about zones →