The TinyPilot frontend runs in the user's browser. It is responsible for:
* Presenting the target computer's video stream in the browser window
* Forwarding keyboard and mouse input to the [TinyPilot backend](#tinypilot-backend)
* Offering friendly interfaces for the user to change TinyPilot's settings
- Presenting the target computer's video stream in the browser window
- Forwarding keyboard and mouse input to the [TinyPilot backend](#tinypilot-backend)
- Offering friendly interfaces for the user to change TinyPilot's settings
The TinyPilot frontend is a pure HTML/CSS/JS app. It has no build or compilation step and no framework like Vue, Angular, or React. It uses external libraries as little as possible.
@ -22,12 +22,12 @@ TinyPilot's custom elements can be found in [app/templates/custom-elements](./ap
The backend is a Flask application. It offers handles three types of requests:
* Page requests
* To serve a page like the main `/` view, TinyPilot uses Flask to pre-render a template.
* REST requests
* When the frontend makes a request to the backend to query server state or perform some action (e.g., `/api/shutdown`), the backend handles it through REST handlers.
* WebSockets requests
* To handle requests for keystrokes or mouse movements, the backend needs something faster than regular HTTP REST requests, so it uses a WebSockets channel.
- Page requests
- To serve a page like the main `/` view, TinyPilot uses Flask to pre-render a template.
- REST requests
- When the frontend makes a request to the backend to query server state or perform some action (e.g., `/api/shutdown`), the backend handles it through REST handlers.
- WebSockets requests
- To handle requests for keystrokes or mouse movements, the backend needs something faster than regular HTTP REST requests, so it uses a WebSockets channel.
The backend is responsible for sending keyboard and mouse input to the target computer via its USB gadgets (see [USB gadgets](#usb-gadgets) section, below).
* If you're making a small change, submit a PR to show your proposal.
* If you're making a large change (over 100 LOC or three hours of dev time), [file an issue](https://github.com/tiny-pilot/tinypilot/issues/new/choose) first to talk through the proposed change. This prevents you from wasting time on a change that has a low chance of being accepted.
- If you're making a small change, submit a PR to show your proposal.
- If you're making a large change (over 100 LOC or three hours of dev time), [file an issue](https://github.com/tiny-pilot/tinypilot/issues/new/choose) first to talk through the proposed change. This prevents you from wasting time on a change that has a low chance of being accepted.
## How to get your PR merged quickly
* Read my guide, ["How to Make Your Code Reviewer Fall in Love with You,"](https://mtlynch.io/code-review-love/) to understand how to contribute effectively to an open source project.
* Give a clear, one-line title to your PR.
* Good: `Fix dropped keystrokes on Firefox`
* Bad: `Fix issue`
* If your PR is not ready for review, mark it as "draft."
* [Rebase your changes](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase) onto the latest `master` commit so that there are no merge conflicts.
* Your PR must pass build checks in CI before it will be considered for merge.
* You'll see a green checkmark or red X next to your PR depending on whether your build passed or failed.
* You are responsible for fixing formatting and tests to ensure that your code passes build checks in CI.
- Read my guide, ["How to Make Your Code Reviewer Fall in Love with You,"](https://mtlynch.io/code-review-love/) to understand how to contribute effectively to an open source project.
- Give a clear, one-line title to your PR.
- Good: `Fix dropped keystrokes on Firefox`
- Bad: `Fix issue`
- If your PR is not ready for review, mark it as "draft."
- [Rebase your changes](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase) onto the latest `master` commit so that there are no merge conflicts.
- Your PR must pass build checks in CI before it will be considered for merge.
- You'll see a green checkmark or red X next to your PR depending on whether your build passed or failed.
- You are responsible for fixing formatting and tests to ensure that your code passes build checks in CI.
I try to review all PRs within one business day. If you've been waiting longer than this, feel free to comment on the PR to verify that it's on my radar.
@ -16,11 +16,11 @@ Turn your Raspberry Pi into a browser-based KVM.
## Features
* Video capture (HDMI/DVI/VGA)
* Keyboard forwarding
* Mouse forwarding
* Fullscreen mode
* Paste text from clipboard
- Video capture (HDMI/DVI/VGA)
- Keyboard forwarding
- Mouse forwarding
- Fullscreen mode
- Paste text from clipboard
## Official builds
@ -34,28 +34,28 @@ Voyager 2 is TinyPilot's professional-grade KVM over IP device. Its quiet, compa
## Build your own
* [Raspberry Pi 4](https://smile.amazon.com/dp/B07TD42S27) (all variants work)
* [HDMI to USB dongle](https://smile.amazon.com/dp/B08CXWPYQ8/)
* [In smaller form factor](https://smile.amazon.com/dp/B08C9FCF2X/)
* They have no brand name, and there are several variants, but they're all built on the same MacroSilicon 2109 chip.
* They're available for $10-15 on eBay and AliExpress.
* [3 Amp power supply](https://smile.amazon.com/dp/B0728HB18G)
* [USB-C to USB-A](https://smile.amazon.com/dp/B01GGKYN0A/) cable (Male/Male)
* [microSD card](https://smile.amazon.com/dp/B073K14CVB/) (Class 10, 8 GB or larger)
* [HDMI to HDMI cable](https://smile.amazon.com/dp/B014I8SSD0/)
* Or \[other\] to HDMI, depending on how your target machine displays output.
* (Optional) [A USB-C OTG split connector](https://tinypilotkvm.com/product/tinypilot-power-connector): Supports continuous power when the target computer turns off.
* Requires two additional [USB-A to microUSB cables](https://smile.amazon.com/dp/B01JPDTZXK/) and a [3 Amp power adapter](https://smile.amazon.com/dp/B0728HB18G).
* If you're using this split connector, choose a USB-C to USB-A cable that's [12" or shorter](https://smile.amazon.com/dp/B012V56D2A/) to minimize voltage drop along the cable.
* (Optional) [VGA to HDMI Adapter](https://smile.amazon.com/dp/B07121Y1Z3/)
* If your target computer has VGA output, the above adapter is [confirmed to work](https://github.com/tiny-pilot/tinypilot/issues/76#issuecomment-664736402) with TinyPilot.
See ["TinyPilot: Build a KVM Over IP for Under $100"](https://mtlynch.io/tinypilot/#how-to-build-your-own-tinypilot) for a more detailed tutorial on how to assemble these parts to create a TinyPilot.
- [Raspberry Pi 4](https://smile.amazon.com/dp/B07TD42S27) (all variants work)
- [HDMI to USB dongle](https://smile.amazon.com/dp/B08CXWPYQ8/)
- [In smaller form factor](https://smile.amazon.com/dp/B08C9FCF2X/)
- They have no brand name, and there are several variants, but they're all built on the same MacroSilicon 2109 chip.
- They're available for \$10-15 on eBay and AliExpress.
- [3 Amp power supply](https://smile.amazon.com/dp/B0728HB18G)
- [USB-C to USB-A](https://smile.amazon.com/dp/B01GGKYN0A/) cable (Male/Male)
- [microSD card](https://smile.amazon.com/dp/B073K14CVB/) (Class 10, 8 GB or larger)
- [HDMI to HDMI cable](https://smile.amazon.com/dp/B014I8SSD0/)
- Or \[other\] to HDMI, depending on how your target machine displays output.
- (Optional) [A USB-C OTG split connector](https://tinypilotkvm.com/product/tinypilot-power-connector): Supports continuous power when the target computer turns off.
- Requires two additional [USB-A to microUSB cables](https://smile.amazon.com/dp/B01JPDTZXK/) and a [3 Amp power adapter](https://smile.amazon.com/dp/B0728HB18G).
- If you're using this split connector, choose a USB-C to USB-A cable that's [12" or shorter](https://smile.amazon.com/dp/B012V56D2A/) to minimize voltage drop along the cable.
- (Optional) [VGA to HDMI Adapter](https://smile.amazon.com/dp/B07121Y1Z3/)
- If your target computer has VGA output, the above adapter is [confirmed to work](https://github.com/tiny-pilot/tinypilot/issues/76#issuecomment-664736402) with TinyPilot.
See ["TinyPilot: Build a KVM Over IP for Under \$100"](https://mtlynch.io/tinypilot/#how-to-build-your-own-tinypilot) for a more detailed tutorial on how to assemble these parts to create a TinyPilot.
## Pre-requisites
* Raspberry Pi OS Stretch or later
* python3-venv
- Raspberry Pi OS Stretch or later
- python3-venv
## Simple installation
@ -72,16 +72,16 @@ curl \
The installation process:
* Creates a service account for TinyPilot with limited priviliges.
* Installs TinyPilot as a systemd service so it runs automatically on every boot.
* Installs and configures TinyPilot's dependencies:
* nginx, which listens on 0.0.0.0:80
* uStreamer, which listens on 127.0.0.1:8001
* Installs TinyPilot to the `/opt/tinypilot` directory.
- Creates a service account for TinyPilot with limited priviliges.
- Installs TinyPilot as a systemd service so it runs automatically on every boot.
- Installs and configures TinyPilot's dependencies:
- nginx, which listens on 0.0.0.0:80
- uStreamer, which listens on 127.0.0.1:8001
- Installs TinyPilot to the `/opt/tinypilot` directory.
When your Pi reboots, you should be able to access TinyPilot by visiting your Pi hostname in the browser. For example, if your device is named `raspberrypi`:
* [http://raspberrypi/](http://raspberrypi/)
- [http://raspberrypi/](http://raspberrypi/)
## Developer installation
@ -89,8 +89,8 @@ See the [CONTRIBUTING](CONTRIBUTING.md) file.
* [TinyPilot Wiki](https://github.com/tiny-pilot/tinypilot/wiki): Guides for tasks related to TinyPilot.
* [TinyPilot Ansible Role](https://github.com/tiny-pilot/ansible-role-tinypilot): Use [Ansible](https://docs.ansible.com/ansible/latest/index.html) to install TinyPilot and all dependencies as a systemd service.
- [TinyPilot Wiki](https://github.com/tiny-pilot/tinypilot/wiki): Guides for tasks related to TinyPilot.
- [TinyPilot Ansible Role](https://github.com/tiny-pilot/ansible-role-tinypilot): Use [Ansible](https://docs.ansible.com/ansible/latest/index.html) to install TinyPilot and all dependencies as a systemd service.
## Acknowledgments
TinyPilot would not be possible without the excellent and generous work from many open source projects, the most notable of which are listed below:
* [uStreamer](https://github.com/pikvm/ustreamer)
* [Flask](https://github.com/pallets/flask) and [Flask-SocketIO](https://flask-socketio.readthedocs.io/en/latest/)
* [vdesktop](https://github.com/Botspot/vdesktop)
* [litestream](https://litestream.io)
* [Raspberry Pi](https://www.raspberrypi.org/)
* [nginx](https://nginx.org/) and [ansible-role-nginx](https://github.com/geerlingguy/ansible-role-nginx)
- [uStreamer](https://github.com/pikvm/ustreamer)
- [Flask](https://github.com/pallets/flask) and [Flask-SocketIO](https://flask-socketio.readthedocs.io/en/latest/)
- [vdesktop](https://github.com/Botspot/vdesktop)
- [litestream](https://litestream.io)
- [Raspberry Pi](https://www.raspberrypi.org/)
- [nginx](https://nginx.org/) and [ansible-role-nginx](https://github.com/geerlingguy/ansible-role-nginx)
## Mailing list
For news about major TinyPilot releases and other updates about the project, sign up for the TinyPilot mailing list: