Adding "Device Name" RPC for version 2.4 (#60)

* Adding "Device Name" RPC for version 2.4

* Minor spelling fix

* Changes from review related to character encoding

* Changes from review

* Clarify authorization requirement for set hostname and set device name

* Clarifications for wifi scanning auth type

* Changes to device info spec from review

* Fix to ordering of arguments from review

* Apply suggestion from @balloob

---------

Co-authored-by: Paulus Schoutsen <balloob@gmail.com>

Author: yinzara

src/ble.md

@@ -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
 
@@ -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`.
 
 ### RPC Command: Request scanned Wi-Fi networks
 
@@ -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.
 
@@ -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.
@@ -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 the device name first then the hostname. 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            |
+|------|------------------------|
+| 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

src/serial.md

@@ -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:
@@ -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
 
@@ -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.
@@ -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 the device name first then the hostname. 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