Registering Own Devices

Linking Workstations describes the normal case: an administrator sits at a workstation, their Shigoto Sensor sees the devices there, and the partner page links them to a digital workstation. Everything the Shigoto Hub needs to know about those devices arrives through the sensor.

Sometimes there is nobody to do that. A Wi-Fi access point covering the Munich office is not a workstation anyone sits at, a batch of docking stations may be known from an asset database long before the first user arrives, and an area that should show up in reports may have no dedicated desk at all. For these cases the partner system can register devices itself, through the API, and link them to locations of its own.

Two calls are involved:

Call	Purpose
POST /admin/device	Make a device known to the Shigoto Hub (create or update).
POST /admin/pair	Attach one or more known devices to a location.

They are deliberately separate. POST /admin/device never assigns a location, and POST /admin/pair never invents a device: pairing a serial id the Hub does not know is silently ignored. That silence is the reason this page exists — a partner that only calls pair for a device no sensor has ever reported will see no error and no effect.

Both endpoints accept a login token or an API key and require customer administrator rights.

caution

A device is only written to the database once it is paired to a location. Between the two calls it lives in the Hub's memory alone and is lost if the server restarts. Always create and pair in one go rather than registering devices in advance and pairing them later.

Device types and serial ids

Every device has a type and a serial id. The type decides what the device means:

Value	Name	Identifies
2	Monitor	A single workstation, through the display's EDID.
4	Usb	A single workstation, typically through a docking station.
8	NIC	The machine itself — its own network adapter, not a place.
16	Router	An area — everyone behind the same default gateway.
32	Wifi	An area — everyone associated with the same access point.

Monitor, Usb and NIC pin down a concrete desk. Router and Wifi cover an area and are the right choice for the pseudo locations described below.

The serial id is the key of the device inside the account, and it is matched literally. It always consists of three fields joined by semicolons — <manufacturer>;<serial>;<productCode> — and must be written exactly the way a Shigoto Sensor would report the same device. If the two differ in a single character, the sensor's report and your entry describe two different devices, and the location is never recognised.

Type	Layout	Example
2 Monitor	<EDID vendor id, 3 letters>;<EDID serial>;<EDID product code, 4 hex digits>	DEL;J8N4P2A;A1C0
4 Usb	<USB vendor id, 4 hex digits>;<USB serial>;<USB product id, decimal>	17EF;8SSF1234;12354
8 NIC	Ethernet;<MAC>;NIC or WLAN;<MAC>;NIC	Ethernet;a4:bb:6d:1f:0e:22;NIC
16 Router	Network;<MAC of the default gateway>;Gateway	Network;ac:84:c6:11:22:33;Gateway
32 Wifi	Network;<BSSID>;WiFi	Network;ac:84:c6:11:22:33;WiFi

MAC addresses and BSSIDs are written in lowercase hexadecimal, colon separated, one leading zero per byte (0e, never e). The hex digits of the monitor and USB fields are uppercase; the USB product id, by contrast, is decimal.

For Wi-Fi the sensor also reports the SSID as the device name and the frequency band as its info — "CubeFour" and "5 GHz". Follow the same convention for devices you register yourself, so that the device lists in the sensor and in the admin panel stay readable.

Do not construct a serial id from a datasheet. Read it back from a sensor that already sees the device: GET /admin/getDevicesForLocations returns serial ids exactly as the Hub stores them, and that is the string POST /admin/device expects. For an access point, the simplest route is to have one machine associate with it once, then read the value from the Hub.

Example: reporting Wi-Fi coverage as a pseudo location

The goal: everyone working in the Munich office should appear in the reports, whether or not they sit at a linked desk, and the partner system should receive that under an id of its own — WIFI-in-Buero-Muenchen.

There is no digital workstation behind that id. It is a pseudo location: an id the partner system makes up, uses as the external id of a Shigoto location, and recognises again when a status report carries it. The Shigoto Hub treats it like any other location.

Step 1 — register the access point

POST /admin/device
Content-Type: application/json
API-KEY: <your api key>

{
	"serialId": "Network;ac:84:c6:11:22:33;WiFi",
	"deviceType": 32,
	"name": "CubeFour",
	"info": "5 GHz"
}

The response tells you whether the device was created or an existing one was updated:

{
	"id": "6f1c1e64-...",
	"serialId": "Network;ac:84:c6:11:22:33;WiFi",
	"name": "CubeFour",
	"info": "5 GHz",
	"deviceType": 32,
	"ephemeral": false,
	"locationId": null,
	"created": true
}

locationId is null — the device is known, but not yet attached to anything. Calling the endpoint again with the same serialId updates the name, the info and the type; name and info left out of the body keep their current value, and an existing pairing is never touched.

Step 2 — pair it with the pseudo location

POST /admin/pair
Content-Type: application/json
API-KEY: <your api key>

[
	{
		"locationId": "WIFI-in-Buero-Muenchen",
		"locationName": "Munich office (Wi-Fi)",
		"deviceSerialIDs": ["Network;ac:84:c6:11:22:33;WiFi"]
	}
]

locationId is your own id — the one you want to see in the status report — and locationName is what a user sees in the Shigoto Sensor and in the admin panel. If no location with that external id exists yet, it is created.

From now on, a sensor that associates with this access point is reported like any other occupancy:

GET https://<PartnerUrl>/sensor/report
    ?customerId=<customerId>
    &userId=<userId>
    &locationId=WIFI-in-Buero-Muenchen
    &state=occupied
    &count=17

See Reporting Sensor Status for the full parameter list.

caution

An area is not a desk. A Wi-Fi location reports as many people as are within reach of the access point, so count is regularly greater than one and the same user can be reported at their desk and in the Wi-Fi area at the same time. Treat a report for a pseudo location as presence information, not as a desk booking — otherwise the partner system will book a workstation nobody asked for.

Several devices on one location

An office is rarely covered by a single access point, and a BSSID is per radio, not per device — a dual-band access point already has two of them. Every BSSID that should count as "Munich office" becomes its own device on the same location.

Add them one after another: register the device, then pair it with the same locationId. The location already exists at that point and is reused; the new device is added to it, and the devices already paired stay where they are.

[
	{
		"locationId": "WIFI-in-Buero-Muenchen",
		"locationName": "Munich office (Wi-Fi)",
		"deviceSerialIDs": ["Network;ac:84:c6:11:22:34;WiFi"]
	}
]

Several serial ids can also be passed in one call, as long as all of them have been registered before:

"deviceSerialIDs": [
	"Network;ac:84:c6:11:22:33;WiFi",
	"Network;ac:84:c6:11:22:34;WiFi",
	"Network;9e:31:88:04:11:c2;WiFi"
]

GET /admin/getDevicesForLocations?locationIds=<internal location id> lists what is currently attached to a location. To detach a single access point again use GET /admin/unpairDevice?serialId=..., and to clear a whole location GET /admin/unpairLocation?locationId=... — the latter accepts your external id as well, so locationId=WIFI-in-Buero-Muenchen works.

Placing the pseudo location in the building

A pseudo location that hangs in nothing is hard to read: the report is correct, but a user looking at the sensor or the admin panel just sees "Munich office (Wi-Fi)" with no context. POST /admin/pair takes not a single location but the path to it, and that path is what sets the parent of each step. Every entry is the parent of the one that follows; only the last entry — the location itself — carries the devices.

[
	{
		"locationId": "BUILDING-MUC-1",
		"locationName": "Munich, Rosenheimer Str. 12"
	},
	{
		"locationId": "FLOOR-MUC-1-3",
		"locationName": "3rd floor"
	},
	{
		"locationId": "WIFI-in-Buero-Muenchen",
		"locationName": "Munich office (Wi-Fi)",
		"deviceSerialIDs": ["Network;ac:84:c6:11:22:33;WiFi"]
	}
]

The building and the floor are ordinary locations. If your building and floor already exist in Shigoto — because desks below them have been linked before — pass their existing ids and they are reused rather than created a second time. The pseudo location is then a child of the floor, in the same tree as the desks around it, and evaluations over the floor or the building include it.

Both the parent and the name are re-applied on every pair call, which is how you correct them later: repeating the call with a different locationName renames the location, and repeating it under a different path moves it. Send the full path each time, not just the last entry — an entry without a parent above it becomes a top-level location.

note

Only the last entry of the array may carry deviceSerialIDs. Devices listed on an entry that is not the last one are ignored.

Checking the result

GET /admin/getLocations returns every location of the account with its current status, including the pseudo locations and their internal ids. Those internal ids are what GET /admin/getDevicesForLocations expects; your own WIFI-in-Buero-Muenchen stays the external id and is what the status report carries.