Chassis mapping

The Mapping screen lets you label the physical bays of your chassis so drive positions read as bay names instead of raw device paths — and saving the map is also what registers the chassis itself in your account's inventory.

The Mapping screen

Open Mapping in the sidebar. The header band reads Chassis map, and the screen shows one table of the drive connections it has detected — a connected drive is the detected connection, so to map a bay you insert a drive into it.

The table has six columns:

Column	Contents
`Bay`	The bay's label — the part you edit.
`Device`	The drive's device path (e.g. `/dev/sda`).
`Model`	Drive model.
`Serial`	Drive serial number.
`Size`	Drive capacity.
`Link`	The connection's link information.

While the station is enumerating, the screen shows Detecting connections…. If enumeration fails, it shows Detection failed: {msg}. With no drives inserted, it shows No connections detected — insert a drive.

Renaming bays

Every row starts with a default label, Bay {row+1} (rendered muted), and hovering the Bay cell shows Double-click to rename. To name a bay:

Double-click the Bay cell. It becomes an inline text field.
Type the label you use on the physical chassis (1-0, Shelf A / Slot 3, whatever matches your stickers).
Click away or tab out — the edit commits when the field loses focus.

Committing an empty label, or the default Bay N text, clears the override and the row falls back to its default label.

Every committed change saves the entire map — the station posts a full snapshot of all bays, not a delta, so the saved map always matches what the screen shows.

Bay lanes are currently identified by device path (/dev/sda), which is not stable across reboots — the same physical bay can enumerate as a different path next boot. Boot-stable lane keys and the boot-time map lookup that would make labels persist across boots on the station are planned; see Planned: boot-time lookup below.

POST/api/chassis_map

Saving the map

Each commit triggers this call automatically — you never invoke it by hand, but it's useful to know what leaves the station. The request is authenticated with the device token as a Bearer credential, like every other station call.

The body carries the station's boot record id, its version, the complete hardware fingerprint of the host chassis, and the map itself: one entry per bay, each with a lane (the connection key — currently the device path) and a label (your bay name).

Request fields

Name
record_id
Type
string
Description
The station's boot record id (e.g. CW-20260623-221305).
Name
engine_version
Type
string
Description
The station's version string.
Name
fingerprint
Type
object
Description
The full hardware fingerprint of the host chassis — system, CPU, memory, GPUs, batteries, storage.
Name
map.bays
Type
array
Description
One object per bay: lane (connection key) and label (bay name). Both must be non-blank for a bay to be saved.

What the save does

The map is keyed by the chassis's DMI UUID + serial, unique per account — resaving from the same chassis updates the same map, and a map name already stored on the server is preserved if not resent.
The bundled fingerprint doubles as the chassis's inventory report: saving a map creates (or updates) an asset for the chassis, so the chassis itself appears in Inventory alongside the machines your engines process.

Request

POST

/api/chassis_map

{
  "record_id": "CW-20260623-221305",
  "engine_version": "1.0.0",
  "fingerprint": {
    "system": {},
    "cpu": {},
    "memory": {},
    "gpus": [],
    "batteries": [],
    "storage": []
  },
  "map": {
    "bays": [
      { "lane": "/dev/sda", "label": "1-0" },
      { "lane": "/dev/sdb", "label": "1-1" }
    ]
  }
}

Response

{
  "ok": true,
  "chassis_map_id": "cmap_…",
  "asset_id": "…"
}

Errors

The edge gateway rejects a malformed body with 400 {"error":"invalid payload"} unless fingerprint is an object and map.bays is an array. Past the gateway, the server can return:

Status	Body	Meaning
`201`	`{"ok":true, …}`	Map saved.
`404`	`{"error":"unknown token"}`	The device token isn't recognised.
`403`	`{"error":"token revoked"}`, `{"error":"token suspended"}`, or `{"error":"token disabled"}`	The token exists but is not in good standing.
`422`	`{"error":"missing record_id or fingerprint"}`	Required fields absent.
`422`	`{"error":"map has no usable bays"}`	No bay had both a non-blank `lane` and a non-blank `label`.

Where admins see the map

Open Inventory and click through to the chassis's asset page. The map renders as a Bay map section (or Bay map — {name} when the map is named): a Mapped bays row showing {count} · updated {date}, then one row per bay in natural label order.

Lane keys are translated into readable connection labels where possible:

Stored lane	Displayed as
`pci-0000:05:00.0-sas-phy14-lun-0`	`HBA 05:00.0 · phy 14`
`pci-…-sas-exp0x…-phy7-lun-0`	`HBA 03:00.0 0x… · phy 7`
`pci-0000:00:17.0-ata-3`	`SATA port 3`
anything else	shown raw

POST/api/chassis_map/lookup

Planned: boot-time lookup

Planned — the station does not call this yet. The endpoint exists and works server-side, but today's station never fetches its saved map back; bay labels apply only to the boot in which you set them. Wiring the station to call this at every boot — so a mapped chassis lays out its saved bay names automatically — is part of the planned bay-grid model described in the Hotswap station overview.

The lookup takes the chassis's DMI system block and returns the saved map for that chassis (matched by DMI UUID + serial within the account), or found: false if none exists.

Request

POST

/api/chassis_map/lookup

{
  "system": { "…": "DMI system block" }
}

Response (found)

{
  "found": true,
  "map": {
    "name": "…",
    "bays": [{ "lane": "…", "label": "…" }]
  }
}

Response (not found)

{ "found": false }