Skip to content

Adding "Device Name" RPC for version 2.4 #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
balloob merged 9 commits into from
Jan 21, 2026
Merged

Adding "Device Name" RPC for version 2.4 #60

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
2b7e71e
Adding "Device Name" RPC for version 2.4
yinzara Dec 19, 2025
728edc1
Minor spelling fix
yinzara Dec 19, 2025
c7e24e5
Changes from review related to character encoding
yinzara Dec 19, 2025
d74eb93
Changes from review
yinzara Dec 19, 2025
44ef502
Clarify authorization requirement for set hostname and set device name
yinzara Dec 20, 2025
9d3acf1
Clarifications for wifi scanning auth type
yinzara Dec 25, 2025
554382a
Changes to device info spec from review
yinzara Dec 27, 2025
8787c45
Fix to ordering of arguments from review
yinzara Dec 29, 2025
d438906
Apply suggestion from @balloob
balloob Jan 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 43 additions & 6 deletions src/ble.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,16 @@ The client is able to send an `identify` to the Improv service if it is in the s

The client is able to send a `device info` to the Improv service if it is in the states "Require Authorization" and "Authorized". When received, and supported, the gadget will return the device information in the RPC response characteristic.

All strings are assumed to be UTF-8 encoded.

## Revision history

- 1.0 - Initial release
- 2.0 - Added Service Data `4677`
- 2.1 - Added Device Info RPC command
- 2.2 - Added Scan Wifi RPC command
- 2.3 - Added Hostname RPC command
- 2.4 - Added Device Name RPC command

## GATT Services

Expand Down Expand Up @@ -160,9 +163,12 @@ Should only be sent if the capability characteristic indicates that device info

This command will generate an RPC result. There will be at least 4 entries in the list response.

Order of strings: Firmware name, firmware version, hardware chip/variant, device name.
Order of strings: Firmware name, firmware version, hardware chip/variant, device name. Optionally, the OS name and OS
version can be appended if applicable and different from the firmware name/version.

Example without OS Name: `ESPHome`, `2021.11.0`, `esp32-s3-devkitc-1/esp32-s3`, `Temperature Monitor`.

Example: `ESPHome`, `2021.11.0`, `ESP32-C3`, `Temperature Monitor`.
Example with OS Name: `Bluetooth Proxy`, `v1.0.0`, `denky_d4/esp32`, `My Bluetooth Proxy`, `ESPHome`, `2025.12.2`.
Copy link
Contributor Author

@yinzara yinzara Dec 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes discussed with @balloob to device info specification that are non-breaking.


### RPC Command: Request scanned Wi-Fi networks

Expand All @@ -177,11 +183,12 @@ Command ID: `0x04`
| CS | checksum |

This command will trigger one RPC Response which will contain a multiple of 3 strings where the first contains the SSID,
the second the RSSI and the third the authentication type of either WEP, WPA, WPA2 or NO.
the second the RSSI and the third the authentication type of either WEP, WPA, WPA2, WPA2 EAP, WPA3, WAPI or NO. If
multiple authentication types are supported they should be separated by a forward slash `/`.

Order of strings: Wi-Fi SSID 1, RSSI 1, Auth type 1, Wi-Fi SSID 2, RSSI 2, Auth type 2, ...

Example: `MyWirelessNetwork`, `-60`, `WPA2`, `MyOtherWirelessNetwork`, `-52`, `WEP`,...
Example: `MyWirelessNetwork`, `-60`, `WPA2`, `MyOtherWirelessNetwork`, `-52`, `WPA/WPA2`,...

A response with no strings means no SSID was found.

Expand All @@ -190,7 +197,7 @@ A response with no strings means no SSID was found.
Sends a request for the device to either get or set its hostname.
This operation is only available while the device is Authorized. Sending the command with no data will return
the current hostname in the response. Sending the command with data will set the hostname to the data and also
return the updated hostname in the response.
return the updated hostname in the response. Setting this property requires the device to be in an 'Authorized' state.

Hostnames must conform to [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123) and can contain only letters,
numbers and hyphens with a length of up to 255 characters. Error code `0x05` will be returned if the hostname provided is not acceptable.
Expand All @@ -214,7 +221,37 @@ Set Hostname:
| | bytes of hostname |
| CS | checksum |

This command will trigger one RPC Response which will contain the hostname of the device.
This command will trigger one RPC Response which will contain the hostname of the device. Setting this
property should reset the authorization timeout.

### RPC Command: Get/Set Device Name

Sends a request for the device to either get or set its name. This could mean different things depending on the device
manufacturer. It may alter the default "hostname" or not. If setting both this property and hostname, it is recommended
to set hostname first then device name. Getting this property should return the same value as the Device Info's
Copy link

@arturpragacz arturpragacz Dec 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is it recommended to first set hostname and then device name?

Copy link
Contributor Author

@yinzara yinzara Dec 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because some manufacturers may choose to default the hostname to something based on the device name and if you set host name second you can be sure it isn’t modified by the device when the device name is set

Copy link

@arturpragacz arturpragacz Dec 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Exactly, so it would seem it's better to first set the device name and then the hostname.

Copy link
Contributor Author

@yinzara yinzara Dec 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lol i feel dumb now youre absolutely right

"Device Name" (4th) property. Setting this property requires the device to be in an 'Authorized' state.

Command ID: `0x06`

Get Device Name:

| Byte | Description |
|------|------------------------|
| 06 | command (`0x06`) |
| 00 | 0 data bytes / no data |
| CS | checksum |

Set Device Name:

| Byte | Description |
|-----|--------------------------------|
| 06 | command (`0x06`) |
| XX | length of device name in bytes |
| | bytes of device name |
| CS | checksum |

This command will trigger one RPC Response which will contain the Device Name of the device. Setting this
property should reset the authorization timeout.


### Characteristic: RPC Result
Expand Down
41 changes: 37 additions & 4 deletions src/serial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ The Improv service will receive Wi-Fi credentials from the client via the serial

The Improv client asks for the current state and sends the Wi-Fi credentials.

All strings are assumed to be UTF-8 encoded.

## Packet format

All packets are sent in the following format:
Expand Down Expand Up @@ -143,9 +145,12 @@ Command ID: `0x03`

This command will trigger one packet, the `Device Information` formatted as a RPC result. This result will contain at least 4 strings.

Order of strings: Firmware name, firmware version, hardware chip/variant, device name.
Order of strings: Firmware name, firmware version, hardware chip/variant, device name. Optionally, the OS name and OS
version can be appended if applicable and different from the firmware name/version.

Example without OS Name: `ESPHome`, `2021.11.0`, `esp32-s3-devkitc-1/esp32-s3`, `Temperature Monitor`.

Example: `ESPHome`, `2021.11.0`, `ESP32-C3`, `Temperature Monitor`.
Example with OS Name: `Bluetooth Proxy`, `v1.0.0`, `denky_d4/esp32`, `My Bluetooth Proxy`, `ESPHome`, `2025.12.2`.

### RPC Command: Request scanned Wi-Fi networks

Expand All @@ -172,7 +177,7 @@ The final response (or the first if no networks are found) will have 0 strings i
Sends a request for the device to either get or set its hostname.
This operation is only available while the device is Authorized. Sending the command with no data will return
the current hostname in the response. Sending the command with data will set the hostname to the data and also
return the updated hostname in the response.
return the updated hostname in the response. Setting this property requires the device to be in an 'Authorized' state.

Hostnames must conform to [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123) and can contain only letters,
numbers and hyphens with a length of up to 255 characters. Error code `0x05` will be returned if the hostname provided is not acceptable.
Expand All @@ -195,7 +200,35 @@ Set Hostname:
| 2 | length of hostname |
| 3...X | bytes of hostname |

This command will trigger one RPC Response which will contain the hostname of the device.
This command will trigger one RPC Response which will contain the hostname of the device. Setting this
property should reset the authorization timeout.

### RPC Command: Get/Set Device Name

Sends a request for the device to either get or set its name. This could mean different things depending on the device
manufacturer. It may alter the default "hostname" or not. If setting both this property and hostname, it is recommended
to set hostname first then device name. Getting this property should return the same value as the Device Info's
"Device Name" (4th) property. Setting this property requires the device to be in an 'Authorized' state.

Command ID: `0x06`

Get Device Name:

| Byte | Description |
|------|------------------------|
| 1 | command (`0x06`) |
| 2 | 0 data bytes / no data |

Set Device Name:

| Byte | Description |
|-------|--------------------------------|
| 1 | command (`0x06`) |
| 2 | length of device name in bytes |
| 3...X | bytes of device name |

This command will trigger one RPC Response which will contain the Device Name of the device. Setting this
property should reset the authorization timeout.

## Packet: RPC Result

Expand Down