Metadata-Version: 2.4
Name: OctoPrint-BitBang
Version: 0.1.2
Summary: Remote OctoPrint access with live H.264 video via BitBang WebRTC
Author-email: Rich LeGrand <rich.m.legrand@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/richlegrand/OctoPrint-BitBang
Project-URL: Source, https://github.com/richlegrand/OctoPrint-BitBang
Project-URL: Issues, https://github.com/richlegrand/OctoPrint-BitBang/issues
Keywords: octoprint,octoprint-plugin,bitbang,webrtc,remote-access,3d-printing,h264,raspberry-pi
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Environment :: Web Environment
Classifier: Framework :: Flask
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Printing
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bitbang>=0.1.53
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: numpy>=1.20.0
Dynamic: license-file


# OctoPrint-BitBang

This is an [OctoPrint](https://octoprint.org/) plugin that offers full remote access to your OctoPrint instance including live H.264 video over a single HTTPS shareable link. It uses [BitBang](https://github.com/richlegrand/bitbang) which creates a secure, fast peer-to-peer connection that requires no account, no subscription, port forwarding, tunnel, or VPN.

![BitBang plugin](https://raw.githubusercontent.com/richlegrand/OctoPrint-BitBang/refs/heads/main/assets/octoprint_bitbang.webp)


This is part of the [BitBang project](https://github.com/richlegrand/bitbang). 

## What you get

- **Full remote access:** You get full access from anywhere through a secure HTTPS URL. Configure, upload G-code, start jobs, see live video, etc. 
- **One link, no account set-up:** Remote access, share the URL, share your printer.
- **Live H.264 video:** Frames come straight from the camera, hardware-encoded on Pi 4 (`/dev/video11` V4L2 M2M) and software-encoded on Pi 5 or any other Linux host, then packetized by aiortc and delivered as a WebRTC media stream. CPU footprint is around 40% (single core) on Pi4. 
- **BitBang URL access is optional:** Video streaming works with local access through local network URL also.
- **Pi CSI camera or USB webcam:** Auto-detected (IMX477, IMX219, IMX708, or any V4L2-capable USB webcam). 
- **Camera controls:** Camera selection, live brightness slider, fullscreen button, image flip H/V buttons, and resolution selection (VGA up to 720p).
- **Snapshots and timelapse:** Integrates with OctoPrint's `WebcamProviderPlugin` API -- snapshots are grabbed from the live stream, so no second camera pipeline to configure.
- **Mobile friendly:** BitBang URL works with phones/tablets.
- **PIN protection:** Optional PIN required to access the remote URL.

## Installation

### Plugin Manager (recommended, once accepted into the OctoPrint plugin registry)

In OctoPrint: **Settings → Plugin Manager → Get More**, search for **BitBang**, click **Install**.

### Plugin Manager, install from URL

**Settings → Plugin Manager → Get More → "… from URL"**, then paste:

```
https://github.com/richlegrand/OctoPrint-BitBang/archive/refs/tags/v0.1.1.zip
```

Click **Install**, then restart OctoPrint when prompted.

### pip

Inside your OctoPrint venv:

```bash
pip install https://github.com/richlegrand/OctoPrint-BitBang/archive/refs/tags/v0.1.1.zip
```

Restart OctoPrint.

## Usage

0. If you are using a separate program for camera streaming (e.g. camera-streamer, mjpg-streamer, ustreamer) you should stop these processes before running BitBang plugin to avoid camera access contention. 
1. Point your browser to your local OctoPrint server. Open **Settings → BitBang**.
2. Choose camera from dropdown.

![Camera dropdown](https://raw.githubusercontent.com/richlegrand/OctoPrint-BitBang/refs/heads/main/assets/camera_select.png)

3. Choose resolution.

![Resolution dropdown](https://raw.githubusercontent.com/richlegrand/OctoPrint-BitBang/refs/heads/main/assets/resolution_select.png)

4. Set a PIN (Optional).
5. Save and **restart OctoPrint**.
6. Refresh the OctoPrint tab in your browser. A button labeled BitBang is available in the menu bar -- click it for the URL.

![Camera dropdown](https://raw.githubusercontent.com/richlegrand/OctoPrint-BitBang/refs/heads/main/assets/bitbang_select.png)

![BitBang URL](https://raw.githubusercontent.com/richlegrand/OctoPrint-BitBang/refs/heads/main/assets/bitbang_url.png)


This URL allows remote access to your printer.

## Configuration

All settings live in **Settings → BitBang**:

| Setting | Effect |
|---|---|
| Enabled | Toggle BitBang remote access |
| PIN | Optional 4+ digit PIN prompt on the remote URL |
| Camera | Auto-detect, or select from dropdown list |
| Resolution | VGA → HD (depending on what selected camera supports) |
| Flip horizontal / vertical | Flip video if necessary |

All settings take effect on OctoPrint restart. Full-screen button and brightness slider are overlaid on the video window (Control tab) and update immediately.

## How it works

- The `bitbang-python` package handles WebRTC signaling, identity, and the ASGI interface.
- This plugin wraps it with OctoPrint integration: settings UI, `WebcamProviderPlugin` hooks, camera auto-detect, CSRF-safe cookie handling, and the JavaScript that injects the `<video>` element into OctoPrint's Control tab.
- The bitba.ng cloud acts purely as a signaling relay to broker a direct connection. If a direct connection isn't available, bitba.ng will use TURN instead.

## Privacy

The BitBang plugin connects through the `bitba.ng` cloud signaling service to broker peer-to-peer connections. Here is what `bitba.ng` does and does not see:

- **Signaling:** When the plugin starts, it registers with `bitba.ng` using a public key derived from a locally-generated keypair (the private key never leaves your device). `bitba.ng` sees this public key, the derived UID that becomes part of your URL, and connection metadata (timestamps, IPs of peers attempting to connect).
- **Media path:** Once a peer connects, video and HTTP traffic flow **directly** between the browser and your OctoPrint host over an encrypted WebRTC data channel (DTLS-SRTP). `bitba.ng` does not see this traffic.
- **TURN fallback:** If a direct connection cannot be established (strict NAT/firewall), `bitba.ng` may relay the *encrypted* WebRTC stream via TURN. Even in that case, the relay sees ciphertext only — it cannot decrypt your video, OctoPrint UI, or credentials.
- **No account, no tracking:** The plugin does not create an account, send telemetry, or upload usage data.
- **Access control:** Anyone with your URL can reach your OctoPrint instance. Set a **PIN** in the plugin settings to require a passcode on the remote URL.

See the [BitBang project page](https://github.com/richlegrand/bitbang) for the full signaling protocol and identity specifications.

## Supported hardware

- **Raspberry Pi 4** -- hardware H.264 on Pi 4 via V4L2 M2M; tested with IMX477, IMX219
- **Raspberry Pi 5** -- software H.264 via picamera2's `LibavH264Encoder`; 720p@30 comfortably
- **Generic Linux PC/laptop/SBC with webcam** -- software H.264 via aiortc
- **USB webcams** -- any device that offers a V4L2 capture format; aiortc software-encodes to H.264

## License

MIT. See [LICENSE](LICENSE).

## Credits

Built on [aiortc](https://github.com/aiortc/aiortc), [picamera2](https://github.com/raspberrypi/picamera2), and the [bitbang-python](https://github.com/richlegrand/bitbang-python) library. Plugin scaffold uses OctoPrint's [plugin API](https://docs.octoprint.org/en/master/plugins/).

## Contributing

Issues and PRs are welcome. 
