[For builders](https://dotcipher.github.io/hardpoint/format.html) / Vocabulary

# Vocabulary

A capability id means the same thing on every device, so a rule or an AI can ask for battery.level without knowing the hardware.

## Kinds

reading:

A value you can read.

event:

A stream of things that happen.

control:

A value you can set.

action:

Something you can trigger once.

## Privacy

open:

The value can be passed on as it is.

aggregate:

Only counts and coarse states may leave the adapter, never the raw stream.

presence:

Only whether it is in use or present may leave the adapter, never the content.

## Capabilities

| Capability | Kind | Lowest risk allowed | Devices |
| --- | --- | --- | --- |
| identity.firmware Firmware version or layout identifier the device reports. | reading string | read | [AirPods Pro](https://dotcipher.github.io/hardpoint/devices/apple-airpods-pro-200e.html), [Noise Cancelling Headphones 700](https://dotcipher.github.io/hardpoint/devices/bose-nc-700.html), [TS3 Plus](https://dotcipher.github.io/hardpoint/devices/caldigit-ts3-plus.html), [MX Master 3](https://dotcipher.github.io/hardpoint/devices/logitech-mx-master-3.html), [TU690T Crystal UHD 4K TV](https://dotcipher.github.io/hardpoint/devices/samsung-tu690t.html), [Moonlander Mark I](https://dotcipher.github.io/hardpoint/devices/zsa-moonlander-mk1.html), [Voyager](https://dotcipher.github.io/hardpoint/devices/zsa-voyager.html) |
| keys.position_events Every key press and release, by physical position. | event key position, down or up | read aggregate | [Moonlander Mark I](https://dotcipher.github.io/hardpoint/devices/zsa-moonlander-mk1.html), [Voyager](https://dotcipher.github.io/hardpoint/devices/zsa-voyager.html) |
| keys.layer The active keymap layer, reported when it changes. | event layer number | read | [Moonlander Mark I](https://dotcipher.github.io/hardpoint/devices/zsa-moonlander-mk1.html) |
| keys.layer_set Switch the active keymap layer from the host. | control layer number | guarded | [Moonlander Mark I](https://dotcipher.github.io/hardpoint/devices/zsa-moonlander-mk1.html) |
| light.per_key Set the colour of an individual key. | control rgb per key | reversible | [Moonlander Mark I](https://dotcipher.github.io/hardpoint/devices/zsa-moonlander-mk1.html) |
| light.global Set every light on the device to one colour, or hand lighting back to the firmware. | control rgb | reversible | [Moonlander Mark I](https://dotcipher.github.io/hardpoint/devices/zsa-moonlander-mk1.html), [Voyager](https://dotcipher.github.io/hardpoint/devices/zsa-voyager.html) |
| light.status Switch the device's separate indicator lights. | control on or off per indicator | reversible | [Moonlander Mark I](https://dotcipher.github.io/hardpoint/devices/zsa-moonlander-mk1.html) |
| firmware.flash Replace the device's firmware. | action firmware image | gated | [Moonlander Mark I](https://dotcipher.github.io/hardpoint/devices/zsa-moonlander-mk1.html), [Voyager](https://dotcipher.github.io/hardpoint/devices/zsa-voyager.html) |
| battery.level Charge remaining. | reading percent | read | [AirPods Pro](https://dotcipher.github.io/hardpoint/devices/apple-airpods-pro-200e.html), [MacBook Pro (14-inch, 2024)](https://dotcipher.github.io/hardpoint/devices/apple-macbook-pro-mac16-6.html), [Noise Cancelling Headphones 700](https://dotcipher.github.io/hardpoint/devices/bose-nc-700.html), [MX Master 3](https://dotcipher.github.io/hardpoint/devices/logitech-mx-master-3.html) |
| battery.charging Whether the battery is charging. | reading boolean | read | [MacBook Pro (14-inch, 2024)](https://dotcipher.github.io/hardpoint/devices/apple-macbook-pro-mac16-6.html) |
| battery.cycles Charge cycles so far. | reading count | read | [MacBook Pro (14-inch, 2024)](https://dotcipher.github.io/hardpoint/devices/apple-macbook-pro-mac16-6.html) |
| battery.health Capacity now, relative to when the battery was new. | reading percent | read | [MacBook Pro (14-inch, 2024)](https://dotcipher.github.io/hardpoint/devices/apple-macbook-pro-mac16-6.html) |
| storage.health The drive's own health verdict. | reading status | read | [MacBook Pro (14-inch, 2024)](https://dotcipher.github.io/hardpoint/devices/apple-macbook-pro-mac16-6.html), [Expansion external drive](https://dotcipher.github.io/hardpoint/devices/seagate-expansion-2322.html) |
| thermal.pressure Whether the system is limiting performance because of heat. | reading level | read | [MacBook Pro (14-inch, 2024)](https://dotcipher.github.io/hardpoint/devices/apple-macbook-pro-mac16-6.html) |
| audio.output_volume Output volume. | control percent | reversible | [MacBook Pro (14-inch, 2024)](https://dotcipher.github.io/hardpoint/devices/apple-macbook-pro-mac16-6.html), [Chromecast](https://dotcipher.github.io/hardpoint/devices/google-chromecast.html) |
| pointer.dpi Pointer sensitivity. | control dots per inch | guarded | [MX Master 3](https://dotcipher.github.io/hardpoint/devices/logitech-mx-master-3.html) |
| pointer.buttons Send a button's presses to software instead of its built-in action. | control button to software | guarded | [MX Master 3](https://dotcipher.github.io/hardpoint/devices/logitech-mx-master-3.html) |
| pointer.host Move the device to another paired computer. | control host number | gated | [MX Master 3](https://dotcipher.github.io/hardpoint/devices/logitech-mx-master-3.html) |
| scroll.mode How the scroll wheel behaves. | control ratchet or free-spin | reversible | [MX Master 3](https://dotcipher.github.io/hardpoint/devices/logitech-mx-master-3.html) |
| display.input Which video input the display shows. | control input source | guarded | [UltraWide display](https://dotcipher.github.io/hardpoint/devices/lg-ultrawide-76fe.html) |
| display.brightness Display brightness. | control percent | reversible | [UltraWide display](https://dotcipher.github.io/hardpoint/devices/lg-ultrawide-76fe.html) |
| media.playing Whether something is playing. | reading playing or idle | read presence | [Chromecast](https://dotcipher.github.io/hardpoint/devices/google-chromecast.html) |
| climate.temperature The temperature the device measures. | reading degrees | read | [Window air conditioner](https://dotcipher.github.io/hardpoint/devices/ge-window-ac.html) |
| climate.target The temperature the device aims for. | control degrees | reversible | [Window air conditioner](https://dotcipher.github.io/hardpoint/devices/ge-window-ac.html) |
| power.switch Switch the device itself on or off. | control on or off | reversible | [Window air conditioner](https://dotcipher.github.io/hardpoint/devices/ge-window-ac.html), [Light](https://dotcipher.github.io/hardpoint/devices/home-assistant-light.html) |
| power.outlet Switch power to whatever is plugged into the device. | control on or off | gated | [Outlet / smart plug](https://dotcipher.github.io/hardpoint/devices/home-assistant-outlet.html) |
| light.brightness How bright a light is. | control percent | reversible | [Light](https://dotcipher.github.io/hardpoint/devices/home-assistant-light.html) |
| access.unlock Unlock a door. | action none | gated | [Lock](https://dotcipher.github.io/hardpoint/devices/home-assistant-lock.html) |
