Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/improv-wifi/sdk-serial-js
JavaScript SDK to add Improv Wi-Fi over serial to your website.
https://github.com/improv-wifi/sdk-serial-js
esp32 esp8266 webserial wifi-provisioning
Last synced: 22 days ago
JSON representation
JavaScript SDK to add Improv Wi-Fi over serial to your website.
- Host: GitHub
- URL: https://github.com/improv-wifi/sdk-serial-js
- Owner: improv-wifi
- License: apache-2.0
- Created: 2021-10-29T07:29:16.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-05-08T15:57:53.000Z (over 1 year ago)
- Last Synced: 2024-10-04T05:34:26.062Z (about 1 month ago)
- Topics: esp32, esp8266, webserial, wifi-provisioning
- Language: TypeScript
- Homepage: https://www.improv-wifi.com
- Size: 486 KB
- Stars: 12
- Watchers: 2
- Forks: 7
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# JavaScript SDK for Improv Wi-Fi over Serial
## Installation
If you are using a bundler and JavaScript package manager, you can install the SDK via NPM:
```
npm install --save improv-wifi-sdk
```
And then import it in your code:
```
import 'improv-wifi-serial-sdk';
```
## Usage
Add the following to your website to show a button to start the provisioning process:
```html
```
A warning message will be rendered if the browser does not support WebSerial.
The SDK will render an error when the connected device does not support Improv. If it is opt-in for your software, you can set a link as the `learnMoreUrl` attribute to include this link in the error message.
```html
```
### Attributes
The following attributes are automatically added to `` and can be used for styling:
| Attribute | Description |
| -- | -- |
| `supported` | Added if this browser is supported
| `unsupported` | Added if this browser is not supported
### Slots
It is possible to customize the button and the message. You do this by putting your elements inside the `` element and adding the appropriate `slot` attribute. Use `activate` to replace the activation button and `unsupported` to replace the unsupported message:
```html
Start provisioning!
Your browser does not support provisioning.
```
### Events
When the dialog is closed, a `closed` event will be fired on both `` and ``. This event will have a `detail` property with the following properties:
- `improv`: Boolean indicating if we connected to a device running Improv.
- `provisioned`: Boolean indicating if the device is connected to Wi-Fi.
## Browser Support
This SDK requires a browser with support for WebSerial. Currently this is supported by Google Chrome, Microsoft Edge and other browsers based on the Blink engine.
No iOS devices are supported.
## Standalone usage
The serial SDK can also be used standalone without the UI.
```ts
import { ImprovSerial } from "improv-wifi-serial-sdk/dist/serial.ts";
const port = await navigator.serial.requestPort();
await port.open({ baudRate: 115200 });
const improv = new ImprovSerial(port, console);
improv.addEventListener("state-changed", console.log);
improv.addEventListener("error-changed", console.log);
await improv.initialize();
improv.addEventListener("disconnect", console.log);
console.log({
info: improv.info,
nextUrl: improv.nextUrl,
});
await improv.provision(
"My Wifi",
"My password",
30000 // Optional: Timeout in ms
);
```