From e6dc819b6d45b146b1eae0617b531fdd24cdfdd8 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Thu, 1 Jul 2021 13:53:04 +1200 Subject: [PATCH 01/14] Add initial doc for imperial --- src/imperial.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 src/imperial.md diff --git a/src/imperial.md b/src/imperial.md new file mode 100644 index 0000000..215be1b --- /dev/null +++ b/src/imperial.md @@ -0,0 +1,101 @@ +--- +layout: base +title: Documentation +description: +--- + +## Imperial Service + +... (To be written) + +### Serial packet format + +| Byte | Purpose | +| ------ | ------------------------------- | +| 1-8 | Header will equal `IMPERIAL` | +| 9 | Type (see below) | +| 10 | Length | +| 11...X | Data | +| X + 11 | Checksum (Not for RPC/Response) | + + +### Current State (_Device to client_) + +Current state type: `0x01` + +The current status of the provisioning service and will write and notify any listening clients for instant feedback. + +| Value | State | Purpose | +| ------ | ---------------------- | ------------------------------------------------ | +| `0x02` | Ready (Authorized) | Ready to accept credentials. | +| `0x03` | Provisioning | Credentials received, attempt to connect. | +| `0x04` | Provisioned | Connection successful. | + +### Error state (_Device to client_) + +Error state type: `0x02` + +This message will be sent with the current error state if it changes for instant feedback. + +| Value | State | Purpose | +| ------ | ------------------- | --------------------------------------------------------------------------------------- | +| `0x00` | No error | This shows there is no current error state. | +| `0x01` | Invalid RPC packet | RPC packet was malformed/invalid. | +| `0x02` | Unknown RPC command | The command sent is unknown. | +| `0x03` | Unable to connect | The credentials have been received and an attempt to connect to the network has failed. | +| `0xFF` | Unknown Error | | + +### RPC (_Client to device_) + +RPC type: `0x03` + +This message type is used for the client to send commands to the device. + +| Byte | Description | +| ----- | ----------------------------------------------------- | +| 1 | Command (see below) | +| 2 | Data length | +| 3...X | Data | +| X + 3 | Checksum - A simple sum checksum keeping only the LSB | + +#### RPC Command: Send Wi-Fi settings + +Submit Wi-Fi credentials to the Improv Service to attempt to connect to. + +Command ID: `0x01` + +| Byte | Description | +| ---- | --------------- | +| 01 | command | +| xx | data length | +| yy | ssid length | +| | ssid bytes | +| zz | password length | +| | password bytes | +| CS | checksum | + +Example: SSID = MyWirelessAP, Password = mysecurepassword + +``` +01 1E 0C {MyWirelessAP} 10 {mysecurepassword} CS +``` + +This command will generate an RPC result. The first entry in the list is an URL to redirect the user to. If there is no URL, omit the entry or add an empty string. + + +### RPC Result (_Device to client_) + +RCP response type: `0x04` + +This message type contains the response to a RPC command. Results are returned as a list of strings. An empty list is allowed. + +| Byte | Description | +| --------- | ----------------------------------------------------- | +| 1 | Command (see below) | +| 2 | Data length | +| 3 | Length of string 1 | +| 4...X | String 1 | +| X | Length of string 2 | +| X...Y | String 2 | +| ... | etc | +| last byte | Checksum - A simple sum checksum keeping only the LSB | From 73d155db5f037837b4ad6d8e0511ab378a70db70 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 24 Aug 2021 06:45:40 +1200 Subject: [PATCH 02/14] Add version byte --- src/imperial.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/imperial.md b/src/imperial.md index 215be1b..bd41c90 100644 --- a/src/imperial.md +++ b/src/imperial.md @@ -13,10 +13,11 @@ description: | Byte | Purpose | | ------ | ------------------------------- | | 1-8 | Header will equal `IMPERIAL` | -| 9 | Type (see below) | -| 10 | Length | -| 11...X | Data | -| X + 11 | Checksum (Not for RPC/Response) | +| 9 | Version CURRENT VERSION = `1` | +| 10 | Type (see below) | +| 11 | Length | +| 12...X | Data | +| X + 12 | Checksum (Not for RPC/Response) | ### Current State (_Device to client_) From 0f15fa045daceafe38d3cdfcd714837a0b0e1d85 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 24 Aug 2021 09:59:07 +1200 Subject: [PATCH 03/14] Add command 0x02 to request current state from device. --- src/imperial.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/imperial.md b/src/imperial.md index bd41c90..8974159 100644 --- a/src/imperial.md +++ b/src/imperial.md @@ -83,6 +83,16 @@ Example: SSID = MyWirelessAP, Password = mysecurepassword This command will generate an RPC result. The first entry in the list is an URL to redirect the user to. If there is no URL, omit the entry or add an empty string. +#### RPC Command: Request current state + +Sends a request for the device to send the current state of imperial to the client. + +Command ID: `0x02` + +| Byte | Description | +| ---- | --------------- | +| 01 | command (0x02) | + ### RPC Result (_Device to client_) From 5643c20386e9ef8af0c6c0d0e9dd08c1266ef06b Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 24 Aug 2021 10:23:15 +1200 Subject: [PATCH 04/14] Add message about response for requesting current state Fix some table bytes to be indexes --- src/imperial.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/src/imperial.md b/src/imperial.md index 8974159..2d0873e 100644 --- a/src/imperial.md +++ b/src/imperial.md @@ -1,12 +1,12 @@ --- layout: base -title: Documentation +title: Imperial description: --- ## Imperial Service -... (To be written) +Imperial is Improv via Serial and allows a client to send the Wi-Fi credentials to a device to save via a serial connection. ### Serial packet format @@ -65,15 +65,15 @@ Submit Wi-Fi credentials to the Improv Service to attempt to connect to. Command ID: `0x01` -| Byte | Description | -| ---- | --------------- | -| 01 | command | -| xx | data length | -| yy | ssid length | -| | ssid bytes | -| zz | password length | -| | password bytes | -| CS | checksum | +| Byte | Description | +| ----- | ---------------- | +| 1 | command (`0x01`) | +| 2 | data length | +| 3 | ssid length | +| 4...X | ssid bytes | +| X | password length | +| X...Y | password bytes | +| Y | checksum | Example: SSID = MyWirelessAP, Password = mysecurepassword @@ -89,9 +89,11 @@ Sends a request for the device to send the current state of imperial to the clie Command ID: `0x02` -| Byte | Description | -| ---- | --------------- | -| 01 | command (0x02) | +| Byte | Description | +| ---- | ---------------- | +| 1 | command (`0x02`) | + +This command will trigger two packets, the `Current State` (see above) and the same response you would get if device provisioning was successful (see below). ### RPC Result (_Device to client_) @@ -102,7 +104,7 @@ This message type contains the response to a RPC command. Results are returned a | Byte | Description | | --------- | ----------------------------------------------------- | -| 1 | Command (see below) | +| 1 | Command being responded to (see above) | | 2 | Data length | | 3 | Length of string 1 | | 4...X | String 1 | From 4c9f0875bb36498ffd0f9a25e27ed767374d275a Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 24 Aug 2021 15:38:30 +1200 Subject: [PATCH 05/14] Note about packet count --- src/imperial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/imperial.md b/src/imperial.md index 2d0873e..fdb9815 100644 --- a/src/imperial.md +++ b/src/imperial.md @@ -93,7 +93,7 @@ Command ID: `0x02` | ---- | ---------------- | | 1 | command (`0x02`) | -This command will trigger two packets, the `Current State` (see above) and the same response you would get if device provisioning was successful (see below). +This command will trigger at least one packet, the `Current State` (see above) and if already provisioned, the same response you would get if device provisioning was successful (see below). ### RPC Result (_Device to client_) From fac4d1ed97b560e97d68870dbc19d123d0a4b018 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Mon, 11 Oct 2021 23:10:23 +0000 Subject: [PATCH 06/14] Change imperial to improv via serial --- src/{imperial.md => serial_documentation.md} | 24 ++++++++++++-------- 1 file changed, 14 insertions(+), 10 deletions(-) rename src/{imperial.md => serial_documentation.md} (84%) diff --git a/src/imperial.md b/src/serial_documentation.md similarity index 84% rename from src/imperial.md rename to src/serial_documentation.md index fdb9815..ddc0892 100644 --- a/src/imperial.md +++ b/src/serial_documentation.md @@ -1,23 +1,23 @@ --- layout: base -title: Imperial +title: Improv via Serial description: --- -## Imperial Service +## Improv via Serial Service -Imperial is Improv via Serial and allows a client to send the Wi-Fi credentials to a device to save via a serial connection. +Improv via Serial allows a client to send the Wi-Fi credentials to a device to save via a serial connection. ### Serial packet format | Byte | Purpose | | ------ | ------------------------------- | -| 1-8 | Header will equal `IMPERIAL` | -| 9 | Version CURRENT VERSION = `1` | -| 10 | Type (see below) | -| 11 | Length | -| 12...X | Data | -| X + 12 | Checksum (Not for RPC/Response) | +| 1-6 | Header will equal `IMPROV` | +| 7 | Version CURRENT VERSION = `1` | +| 8 | Type (see below) | +| 9 | Length | +| 10...X | Data | +| X + 10 | Checksum (Not for RPC/Response) | ### Current State (_Device to client_) @@ -31,6 +31,10 @@ The current status of the provisioning service and will write and notify any lis | `0x02` | Ready (Authorized) | Ready to accept credentials. | | `0x03` | Provisioning | Credentials received, attempt to connect. | | `0x04` | Provisioned | Connection successful. | +| 3 | Length of string 1 | +| 4...X | String 1 | +| X | Length of string 2 | +| X...Y | String 2 | ### Error state (_Device to client_) @@ -85,7 +89,7 @@ This command will generate an RPC result. The first entry in the list is an URL #### RPC Command: Request current state -Sends a request for the device to send the current state of imperial to the client. +Sends a request for the device to send the current state of improv to the client. Command ID: `0x02` From 23a25a1d0d3aa1dd4f962e158361c2e0912fe53c Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Mon, 11 Oct 2021 23:11:19 +0000 Subject: [PATCH 07/14] Add improv serial to menu Rename Documentation to BLE Documentation --- src/_includes/base.html | 4 +++- src/documentation.md | 3 +-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/src/_includes/base.html b/src/_includes/base.html index 10e2040..aece89a 100644 --- a/src/_includes/base.html +++ b/src/_includes/base.html @@ -3,7 +3,9 @@ - - / - Home - - /documentation/ - - Documentation + - BLE Documentation + - - /serial_documentation/ + - Serial Documentation - - /code/ - Code --- diff --git a/src/documentation.md b/src/documentation.md index e75f4c5..ecc9f71 100644 --- a/src/documentation.md +++ b/src/documentation.md @@ -1,6 +1,6 @@ --- layout: base -title: Documentation +title: Improv via BLE description: All the implementation details necessary to make your own client and service implementation. --- @@ -143,4 +143,3 @@ This characteristic is where the client can read results from the RPC service if | X...Y | String 2 | | ... | etc | | last byte | Checksum - A simple sum checksum keeping only the LSB | - From b4e5e3789fde35b0c479cc4ed97ba597e463f342 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 12 Oct 2021 03:40:27 +0000 Subject: [PATCH 08/14] Rename ble doc page and add redirect --- public/_redirects | 3 +++ src/{documentation.md => ble.md} | 0 2 files changed, 3 insertions(+) create mode 100644 public/_redirects rename src/{documentation.md => ble.md} (100%) diff --git a/public/_redirects b/public/_redirects new file mode 100644 index 0000000..74ceb68 --- /dev/null +++ b/public/_redirects @@ -0,0 +1,3 @@ +# These redirects are handled by Netlify + +/documentation /ble diff --git a/src/documentation.md b/src/ble.md similarity index 100% rename from src/documentation.md rename to src/ble.md From 231c2943e1c5eca455fa24b178d6178900db653d Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 12 Oct 2021 03:40:39 +0000 Subject: [PATCH 09/14] Rename serial page --- src/{serial_documentation.md => serial.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/{serial_documentation.md => serial.md} (100%) diff --git a/src/serial_documentation.md b/src/serial.md similarity index 100% rename from src/serial_documentation.md rename to src/serial.md From 62153581245cca31166393c17c29cdea8cb4a4d2 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 12 Oct 2021 03:40:56 +0000 Subject: [PATCH 10/14] Update index and template to include serial --- src/_includes/base.html | 10 +++++----- src/index.html | 22 +++++++++++----------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/src/_includes/base.html b/src/_includes/base.html index aece89a..459b7d9 100644 --- a/src/_includes/base.html +++ b/src/_includes/base.html @@ -2,10 +2,10 @@ menu: - - / - Home - - - /documentation/ - - BLE Documentation - - - /serial_documentation/ - - Serial Documentation + - - /ble/ + - BLE + - - /serial/ + - Serial - - /code/ - Code --- @@ -17,7 +17,7 @@ {%- if title -%} {{ title }} – Improv Wi-Fi {%- else -%} -Improv Wi-Fi: Open standard for setting up Wi-Fi via Bluetooth LE +Improv Wi-Fi: Open standard for setting up Wi-Fi via Bluetooth LE and Serial {%- endif -%} {%- endcapture %} {% comment %} diff --git a/src/index.html b/src/index.html index e9804ab..eef546f 100644 --- a/src/index.html +++ b/src/index.html @@ -3,7 +3,7 @@ description: Free and open standard with ready-made SDKs that offer a great user experience to configure Wi-Fi on devices. --- -

Open standard for setting up Wi-Fi via Bluetooth LE

+

Open standard for setting up Wi-Fi via Bluetooth LE and Serial

Improv is a free and open standard with ready-made SDKs that offer a great @@ -59,12 +59,12 @@

Adopted by the following projects

ESPHome

Open source firmware for ESP8266/ESP32 devices that is easy to use.

- Allows configuring Wi-Fi credentials via Improv. - Learn more + Allows configuring Wi-Fi credentials via Improv over BLE. + Learn more +

+

+ Allows configuring Wi-Fi credentials via Improv over Serial. + Learn more

Website @@ -122,16 +122,16 @@

The problem we're solving

Improv Scope & Constraints

The goal of the standard is to get the device connected to the Wi-Fi via - Bluetooth Low Energy (BLE). It is not the goal to offer a way for devices to - share data or control. The standard should work without requiring the device - to contain a screen. + Bluetooth Low Energy (BLE) or Serial (USB/UART). It is not the goal to offer a way + for devices to share data or control. The standard should work without + requiring the device to contain a screen.

More Reading

From e135ca69715db3863fa4eaece85ce767d1f791c3 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 12 Oct 2021 03:44:37 +0000 Subject: [PATCH 11/14] Tidy up ESPHome section --- src/index.html | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/index.html b/src/index.html index eef546f..6495093 100644 --- a/src/index.html +++ b/src/index.html @@ -59,12 +59,8 @@

Adopted by the following projects

ESPHome

Open source firmware for ESP8266/ESP32 devices that is easy to use.

- Allows configuring Wi-Fi credentials via Improv over BLE. - Learn more -

-

- Allows configuring Wi-Fi credentials via Improv over Serial. - Learn more + Allows configuring Wi-Fi credentials via Improv over BLE or Serial.

Website From 9c326090e356f555689e6f6d14f8c6efb8cb6748 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Fri, 5 Nov 2021 15:56:26 -0700 Subject: [PATCH 12/14] Update docs --- public/style.css | 10 ++++-- script/develop | 2 +- src/_includes/base.html | 2 +- src/ble.md | 4 ++- src/code.md | 8 +++-- src/index.html | 62 ++++++++++++++++++++-------------- src/serial.md | 75 +++++++++++++++++++++++++++++------------ 7 files changed, 108 insertions(+), 55 deletions(-) diff --git a/public/style.css b/public/style.css index 6a8a8fa..a87747f 100644 --- a/public/style.css +++ b/public/style.css @@ -55,9 +55,13 @@ h3 { max-width: 100%; overflow-y: scroll; } -improv-wifi-launch-button[supported] { - display: block; - margin-top: 1em; +improv-wifi-launch-button, +improv-wifi-serial-launch-button { + display: inline-block; +} +improv-wifi-launch-button[supported], +improv-wifi-serial-launch-button[supported] { + margin-right: 1em; } .project { display: flex; diff --git a/script/develop b/script/develop index d6c3b30..c342a74 100755 --- a/script/develop +++ b/script/develop @@ -10,6 +10,6 @@ script/download_js_sdk # Quit all background tasks when script exits trap "kill 0" EXIT -npm exec -- serve dist & +npm exec -- serve -p 5005 dist & npm exec -- eleventy --watch & wait diff --git a/src/_includes/base.html b/src/_includes/base.html index 459b7d9..193b1d9 100644 --- a/src/_includes/base.html +++ b/src/_includes/base.html @@ -83,7 +83,7 @@ Improv is an initiative by ESPHome & Home Assistant.
- Initial development funded by + Development funded by Nabu Casa. diff --git a/src/ble.md b/src/ble.md index ecc9f71..6a244f9 100644 --- a/src/ble.md +++ b/src/ble.md @@ -4,7 +4,9 @@ title: Improv via BLE description: All the implementation details necessary to make your own client and service implementation. --- -The Improv Wi-Fi protocol has two actors: the Improv service running on the gadget and the Improv client. +This is the description of the Improv Wi-Fi protocol using Bluetooth Low Energy. + +The protocol has two actors: the Improv service running on the gadget and the Improv client. The Improv service will broadcast its presence via Bluetooth LE and receives Wi-Fi credentials from the client. diff --git a/src/code.md b/src/code.md index ac43e11..ce7e640 100644 --- a/src/code.md +++ b/src/code.md @@ -10,9 +10,9 @@ This page contains software development kits (SDK) and code samples to help you These examples will help you create clients that can provision devices hosting the Improv BLE service. -### SDK for JavaScript +### Bluetooth LE SDK for JavaScript -The SDK for JavaScript contains everything you need to offer Improv provisioning on your website. Simply get started by adding the following HTML snippet: +The Bluetooth LE SDK for JavaScript contains everything you need to offer Improv provisioning using Bluetooth LE on your website. Simply get started by adding the following HTML snippet: ```js