# `Peripheral` A `Peripheral` is one bonded device. The controller or speaker has link keys for this adapter, and the object reports what the radio observes about it. The operator creates the object when pairing succeeds and when it finds a bond that `bluetoothd` already stores. The keys are in a `Secret` this object owns. Read `status.conditions` for the link, `status.battery` for the charge the device reports, and `status.bond` for the keys. Deleting a `Peripheral` is the unpair: the operator disconnects the device, waits for the claim that holds it to release, retires the device from the `ResourceSlice`, and removes the bond from `bluetoothd`, and the `Secret` is collected with the object. Edit `spec.alias` to rename a device and `spec.trusted` to say whether it may reconnect on its own. One bonded Bluetooth device, named for its own address in the same form the ResourceSlice uses. The object owns the Secret that stores this bond's keys. ## spec What the operator makes true about the device. | Field | Type | Required | Description | | --- | --- | --- | --- | | `alias` | string | no | The name for this device, written into BlueZ's Device1.Alias. bluetoothd stores the alias in the bond's own file, so the name is stored with the keys. Leave it empty to keep the name the device reports for itself. | | `trusted` | boolean | no | Whether the device may connect with no agent, written into BlueZ's Device1.Trusted. With this off, BlueZ asks an agent to authorize each service on every connection, and no agent is registered outside a pairing window, so the device does not connect. A trusted controller connects when its own button is pressed. A trusted speaker is connected by the operator whenever it is powered on and in range. Default: `true`. | ## status What the operator observes about the device. | Field | Type | Required | Description | | --- | --- | --- | --- | | `address` | string | no | The device's Bluetooth address, in the uppercase form the label on the hardware shows. | | `name` | string | no | The name the device reports for itself. It is not spec.alias, so a person who renames a device still reads the name the hardware states. | | `icon` | string | no | The freedesktop icon name BlueZ derives for this device, such as input-gaming or audio-headset. It is empty when BlueZ states none. | | `adapter` | string | no | The address of the adapter this bond belongs to. | | `node` | string | no | The machine whose operator holds this bond now. The value changes when the adapter moves. | | `bond` | [object](#statusbond) | no | What the operator observes about the bond. | | `battery` | [object](#statusbattery) | no | The charge the device reports. The operator reads the kernel's power supply class first, and BlueZ's org.bluez.Battery1 interface for a device the kernel registers no power supply for. The block is absent when neither reports a level, which covers every device with no battery and every battery device that is not connected. | | `conditions` | [\[\]object](#statusconditions) | no | Connected reports whether the device has a link now, and its reason says why the link ended, from the reason BlueZ gave. The reason is LinkUp when the link is up. Asleep is a link that timed out on a device that sleeps between sessions, such as a Low Energy remote after an idle hour, and the device's next connect writes one KEY_UNKNOWN press into its virtual device. LinkLost is a link that timed out on a device that does not sleep, which went out of range or whose battery ran out. ClosedByDevice is a link the device ended, and ClosedByRadio is a link this radio ended, at an unpair or at the input recovery. AuthenticationFailed is a link that ended because the keys did not match, and the device needs to be paired again. NotConnected is a link that ended with no reason the operator received: it ended while the operator was not running, or BlueZ reported no reason. NotBonded means bluetoothd holds no object for the device, so the bond was removed by another route. The reason changes only when the link changes, and lastTransitionTime changes only when the status changes. | ### status.bond What the operator observes about the bond. | Field | Type | Required | Description | | --- | --- | --- | --- | | `held` | boolean | no | Whether bluetoothd still has this bond. It is false when the daemon no longer has the keys. The operator reports this state but does not act on it. | | `paired` | boolean | no | Whether BlueZ reports this device as paired, from Device1.Paired, read on every pass the operator makes over the devices. | | `bonded` | boolean | no | Whether BlueZ reports a stored link key for this device, from Device1.Bonded. Paired alone does not state that the key is stored. | | `trusted` | boolean | no | Whether BlueZ reports this device as trusted, from Device1.Trusted. This is the property spec.trusted reconciles into. | | `connected` | boolean | no | Whether BlueZ reports this device as connected, from Device1.Connected. It is the same reading the Connected condition reports. | | `secret` | string | no | The namespace and name of the Secret that stores this bond's keys. The Secret is owned by this object, so deleting the Peripheral collects it. | | `pairedAt` | string | no | When the operator first recorded this bond, which is the pairing for a bond it made and the adoption for one it discovered. | | `request` | string | no | The namespace and name of the PairingRequest that produced this bond. It is empty for a bond the operator adopted. A finished request is collected after its TTL, and this field outlasts it. | ### status.battery The charge the device reports. The operator reads the kernel's power supply class first, and BlueZ's org.bluez.Battery1 interface for a device the kernel registers no power supply for. The block is absent when neither reports a level, which covers every device with no battery and every battery device that is not connected. | Field | Type | Required | Description | | --- | --- | --- | --- | | `percentage` | integer | no | The charge left, from 0 to 100. | | `source` | string | no | Where the level came from. It is the power supply's own name for a reading from the kernel, such as ps-controller-battery-7c:66:ef:22:e7:80, and BlueZ's own word for a reading from BlueZ, such as HID or a GATT service. | | `charging` | boolean | no | Whether the device is charging now. It is absent when the source is BlueZ, which reports a level and no direction, and when the kernel reports the status Unknown. | ### status.conditions[] Connected reports whether the device has a link now, and its reason says why the link ended, from the reason BlueZ gave. The reason is LinkUp when the link is up. Asleep is a link that timed out on a device that sleeps between sessions, such as a Low Energy remote after an idle hour, and the device's next connect writes one KEY_UNKNOWN press into its virtual device. LinkLost is a link that timed out on a device that does not sleep, which went out of range or whose battery ran out. ClosedByDevice is a link the device ended, and ClosedByRadio is a link this radio ended, at an unpair or at the input recovery. AuthenticationFailed is a link that ended because the keys did not match, and the device needs to be paired again. NotConnected is a link that ended with no reason the operator received: it ended while the operator was not running, or BlueZ reported no reason. NotBonded means bluetoothd holds no object for the device, so the bond was removed by another route. The reason changes only when the link changes, and lastTransitionTime changes only when the status changes. | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | string | yes | The state this condition reports on. | | `status` | string | yes | Whether the reported state is true, false, or unknown. One of: `True`, `False`, `Unknown`. | | `reason` | string | no | One word for why the condition has this status. | | `message` | string | no | One sentence on what the reason means, and what a person can do about it when there is something to do. The Event of each transition carries the same sentence. | | `lastTransitionTime` | string | no | When the status last changed, which is not when the operator last wrote the object. A reason that changes under the same status does not move it. |