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 no What the operator observes about the bond.
battery object 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 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.