{"id":20368297,"url":"https://github.com/depau/wi-se-sw","last_synced_at":"2025-07-09T17:04:59.193Z","repository":{"id":61126662,"uuid":"332705109","full_name":"depau/wi-se-sw","owner":"depau","description":"Wi-Se - Wi-Fi Remote Serial/UART Terminal for ESP8266","archived":false,"fork":false,"pushed_at":"2022-09-14T21:30:54.000Z","size":1907,"stargazers_count":35,"open_issues_count":1,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-12T05:38:06.287Z","etag":null,"topics":["esp8266","orange-pi","ota","raspberry","raspberry-pi","serial","ttyd","uart","websocket","wi-fi","wi-se"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/depau.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-25T10:10:13.000Z","updated_at":"2025-03-06T08:37:32.000Z","dependencies_parsed_at":"2022-10-11T12:32:56.677Z","dependency_job_id":null,"html_url":"https://github.com/depau/wi-se-sw","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/depau/wi-se-sw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depau%2Fwi-se-sw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depau%2Fwi-se-sw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depau%2Fwi-se-sw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depau%2Fwi-se-sw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/depau","download_url":"https://codeload.github.com/depau/wi-se-sw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depau%2Fwi-se-sw/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264502119,"owners_count":23618554,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp8266","orange-pi","ota","raspberry","raspberry-pi","serial","ttyd","uart","websocket","wi-fi","wi-se"],"created_at":"2024-11-15T00:40:09.831Z","updated_at":"2025-07-09T17:04:59.122Z","avatar_url":"https://github.com/depau.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wi-Se Remote UART Terminal - C++ implementation\n\n\u003e *Wireless Serial*\n\n![Demo](https://i.postimg.cc/PqRRcwX1/ezgif-com-optimize-1.gif)\n\n---\n\nThis software allows for using an ESP8266 board as a remote UART terminal. It is very fast, reaching (with [caveats](#caveats)) up to\n1500000bps rates.\n\nIt is intended as a firmware for the [Wi-Se](https://github.com/Depau/wi-se-hw/)\nboards (which you can order and build at your favorite PCB manufacturer), though it will work just fine with a normal ESP8266 breakout\nboard.\n\nWith some changes it may work with ESP32 but there's no interest for that at the moment. Pull requests are welcome.\n\nCommunication occurs over WebSockets: it is compatible with\n[ttyd](https://github.com/tsl0922/ttyd/). In fact, the web UI is the same. CLI clients compatible with ttyd, such\nas [ttyc](https://github.com/Depau/ttyc)\nshould also work with Wi-Se.\n\nWi-Se uses a superset of ttyd's protocol. Non Wi-Se-aware clients won't be able to use all features.\n\nWistty can be used to control remote terminal configuration parameters. It is part of ttyc:\nhttps://github.com/Depau/ttyc\n\n## Features\n\n- Web-based terminal based on Xterm.js\n- Very low latency (~10ms on average, depending on your Wi-Fi)\n- Relatively high baud rates are supported (up to ~1500000bps, with\n  [caveats](#caveats))\n- Zmodem support on Web UI\n- Native *nix client: [`ttyc`](https://github.com/Depau/ttyc)\n- OTA firmware updates\n- Automatic baud detection (ymmv)\n- Remote terminal parameters can be changed on the fly\n\n## Building and flashing\n\nBuilding is only supported and tested on GNU/Linux x86_64.\n\nBuilding on Windows is not supported. WSL may work but is not tested. Building on macOS may work but it is not tested. Pull requests are\nwelcome.\n\nRequirements:\n\n- PlatformIO Core ([installation instructions](https://docs.platformio.org/en/latest/core/installation.html#super-quick-mac-linux))\n- Python 3.8+\n\nThe build script also has some additional Python dependencies: `pyjq`, `jinja2`,\n`pyyaml`. You may install them through your distro package manager or use a virtualenv as described here:\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\nTo build and flash the project:\n\n- Inside `configs/`, copy `config.yml.example` to `device_name.yml` and change configuration parameters as needed.\n    - The serial port or IP address for OTA updates must be specified in the config file.\n- Activate Python virtualenv:\n  ```bash\n  source venv/bin/activate\n  ```\n- Build and upload:\n  ```bash\n  ./builder.py upload              # To flash all configured devices\n  ./builder.py upload device_name  # To flash only using \"device_name.yml\"\n  ```\n\nThe `builder.py` script makes it easy to keep a number of devices up-to-date, without having to swap config files.\n\nThe `platformio.ini` and `include/config.h` files are automatically generated by the build script based on each single human-readable YAML\nconfig.\n\nFor development you can change config options in `configs/config.yml.example`, then run `./builder.py devconf --example` to generate the\nheaders in-place.\n\n## Configuration\n\nConfiguration is located under `configs/`. An example config `config.yml.example` is provided, with comments and all options set to their\ndefault values.\n\nRuntime configuration changes are not supported and will not be supported. This helps keep the code simple and reduce security and memory\ncorruption issues.\n\nPushing a OTA firmware update to change the configuration is simple enough.\n\nUART parameters can be changed at runtime, but the original configuration will be restored in case of restart.\n\n## Changing UART parameters at runtime\n\nIdeally it should be implemented in the web page, but I don't know ReactJS (pull-requests welcome). `wistty` (part of `ttyc`) can be used\nto set them. `ttyc` supports setting the UART parameters directly.\n\nIf you don't want to use `wistty` you can change the baud rate and the other parameters by sending an HTTP request:\n\n```bash\ncurl -X POST IP_ADDRESS/stty -H 'Content-Type: application/json' \\\n-d '{\"baudrate\":1500000,\"bits\":8,\"parity\":null,\"stop\":1}'\n\n# To fetch current setting:\ncurl IP_ADDRESS/stty\n\n# For authentication, add:\n--digest --user username:password\n```\n\nBits (data bits) can be `5`, `6`, `7` or `8`, and it must not be `8` if parity is not none.\n\nParity can be `null` (none), `0` (even), `1` (odd).\n\nStop (stop bits) can be `0`, `1`, `2`.\n\nDefaults (`8`, `null`, `1`) will work for most setups.\n\nYou don't have to provide all the parameters, you can provide only the parameters you want to change, for example\n`{\"baudrate\": 115200}`.\n\n## Caveats\n\nESP8266 has incredible capabilities, but fast Wi-Fi isn't one of them.\n\nThe UART works fine with baudrates higher than 1.5 mbps (1500000 bps), however average Wi-Fi transfer speed is usually around 900 kbps.\n\nTo get best performance:\n\n- Avoid the UART to USB adapter built into most ESP8266 devkits (but rather use a better external adapter such as those based on FTDI chips)\n    - The built-in adapter won't go faster than ~500000bps\n- Enable software flow control and make sure it is supported by and enabled on the connected device\n- Avoid sending constant streams of data at high rates if flow control cannot be enabled\n\nThis firmware implements UART software flow control and it is enabled by default.\n\nWith software flow control, Wi-Se asks the connected UART device to momentarily suspend the data transfer (IXON/IXOFF) when the Wi-Fi can't\nkeep up.\n\nThis will improve reliability at high speeds by orders of magnitude.\n\nSee the next section on how to ensure flow control is enabled on Linux-based devices\n\n## Software flow control on Linux\n\nLinux supports flow control and it is usually enabled by default. Some shells (such as `fish`) disable software flow control on start.\n\n`fish` versions prior to 3.2.0 do not support enabling it. Starting from 3.2.0, `fish` will still disable flow control on start up, but it\nwill respect your choice if you enable it in your configuration file.\n\n`bash` and `zsh` usually don't mess with it. However, some \"plug-ins\" may disable it.\n\nAdd the following at the end of your shell configuration file to ensure it is enabled when you login from a terminal.\n\n`~/.bashrc`, `~/.zshrc`, etc.\n\n```bash\ntty | grep -qE '/dev/tty[A-Za-z]+[0-9]*' \u0026\u0026 stty ixon ixoff\n```\n\n`~/.config/fish/config.fish`\n\n```fish\nstring match -rq '/dev/tty[A-Za-z]+\\d*' (tty) \u0026\u0026 stty ixon ixoff\n```\n\n## Troubleshooting\n\n### Terminal is stuck\n\nYou might have pressed `Ctrl`+`S` and triggered flow control by mistake. If you're using `ttyc` you can press `Ctrl`+`Q` to unlock it. If\nyou're using the web client, this will close the browser. Sorry :/ Again, PRs welcome ;)\n\nAnother possible reason is that the firmware crashed. When the firmware crashes, the UART goes out of control until execution restart. This\nmay result in sending a \"break condition\", which causes [`agetty`](https://man.archlinux.org/man/agetty.8) to switch to the next baud rate.\n\nIf you're using `ttyc` you can attempt to manually send more breaks, until the terminal becomes responsive again, or try to perform an\nautomatic baud detection. Every time you send a break, `agetty` will try the next baud rate. Note that if the current console is enabled for\nkernel messages and [SysRq](https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html#how-do-i-use-the-magic-sysrq-key) is enabled you\nhave to send a break twice in a row.\n\nAs a workaround you can change, on connected device, the options passed to `agetty` and configure it to use a single baudrate. On\nsystemd-based distributions you can run `sudo systemctl edit serial-getty@ttyXXX.service` (you can retrieve the TTY by running `tty`), then\nadd\n\n```systemd\n[Service]\nExecStart=\nExecStart=-/sbin/agetty -o '-p -- \\\\u' --keep-baud 115200,57600,38400,9600 %I $TERM\n```\n\nChange the baudrate to whatever you like, then `sudo systemctl restart serial-getty@ttyXXX.service`.\n\n### Terminal output is garbled\n\nSoftware flow control is disabled or not supported/enabled on the connected device. See if running `stty ixon ixoff` on the remote device\nmakes any difference.\n\nIf you can't enable flow control on the connected device, try with low baud rates.\n\n## LEDs meaning\n\nWi-Se boards come with 4 LEDs:\n\n| LED      | Color        |\n| -------- | ------------ |\n| Wi-Fi    | Blue         |\n| Status   | Yellow/Amber |\n| TX       | Red          |\n| RX       | Red          |\n\n#### Wi-Fi LED blinking, status LED on\n\nConnecting to Wi-Fi.\n\n#### Wi-Fi LED on\n\nConnected and operating normally.\n\n#### Wi-Fi LED on, status LED blinking fast (or on)\n\nOperating normally, but flow control is currently blocked. If the status LED doesn't turn off within 0.5 sec there might be a bug.\n\nIt is normal for flow control to occur regularly when there is a lot of terminal activity. However, if it gets stuck turned on it might be\nthe symptom of another issue.\n\n#### TX and RX blink very fast\n\nTerminal activity:\n\n- TX blinks ⇒ WebSocket to UART\n- RX blinks ⇒ UART to WebSocket\n\n#### TX and RX blink one at a time, slowly\n\nDevice error:\n\n- OTA update failed (ensure the OTA host port is enabled in your firewall - OTA requires the devices to be mutually reachable)\n- When in Wi-Fi station (client) mode: disconnected from the wireless network\n\nThe device will restart after around 1 second.\n\n#### OTA LED animations\n\nWhen performing OTA, the device will switch to \"Christmas tree lights mode\" and show a series of animations to report the current status.\n\n- OTA start: LEDs turn on one at a time, twice, in sequence RX, TX, Status, Wi-Fi\n- OTA progress: the LEDs will act as a firmware download progress bar\n- OTA error: RX/TX LEDs blink slowly\n- OTA success: RX, TX and status LEDs will turn off in sequence, Wi-Fi LED will stay on. The device will restart after ~3 sec into the new\n  firmware.\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0.\n\nAll content under `/html` was originally written for\n[ttyd](https://github.com/tsl0922/ttyd/), and it has been slightly modified.\n[ttyd](https://github.com/tsl0922/ttyd/) is licensed under MIT license.\n\nSee the git commit history for the `/html` directory for original authors credits.\n\nSee `fakeesp/README.md` for licensing info for the ESP SDK and libraries mocks.\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdepau%2Fwi-se-sw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdepau%2Fwi-se-sw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdepau%2Fwi-se-sw/lists"}