TeslaUSB Enhanced turns a Raspberry Pi Zero 2 W into a Tesla-compatible USB drive with automatic archiving, music storage, a local dashboard, recovery tools, and a safer first-boot experience.
This is an unofficial derivative of
marcone/teslausb. It keeps the upstream
TeslaUSB workflow while adding a ready-to-flash image, an offline configuration
wizard, stricter security boundaries, verified archive transfers, and guarded
recovery and upgrade tools.
Project links: latest official release · all releases · changelog · setup guide
Important
Version 2.0.0 is being prepared for release. Its new image stays an unpublished draft until the exact build passes testing on a spare card. Back up configuration, keys, and recordings before flashing any image.
The modern dashboard brings together date and hour browsing, front-camera thumbnails, six-camera navigation, original-quality downloads, recording freshness, and recoverable Trash. Load clip first helps playback on slower connections, while Camera overview uses lightweight stills. Original-quality playback is the default; the modern viewer no longer offers slow on-device Low video conversion. Interface guide · Version 2.0 changes
Real six-camera footage from a working installation, shown in All cameras view. These are recorded frames, not a live camera feed. The screenshot preserves the original capture; version 2.0 uses original quality without the older quality selector shown here.
| Item | Status |
|---|---|
| Source version | 2.0.0 |
| New image | Draft build and spare-card acceptance; publication pending |
| Primary hardware | Raspberry Pi Zero 2 W |
| Operating system | 64-bit Raspberry Pi OS Lite, Debian Trixie, arm64 |
| Version 2 image filename | teslausb-enhanced-v2.0.0-pi-zero-2w-arm64-trixie.img.xz |
| Image integrity | Use the matching .img.xz.sha256, .image-metadata.json, and .packages.tsv assets from the same release |
| Available public downloads | Published releases |
Both automatic and manual image builds stay drafts. The workflow checks the source, image, and uploaded checksums, then records the exact image SHA-256 for a spare-card test. Publication follows successful setup, car recording, Sentry, archiving, downloads, and recovery checks of that same image. Rebuilding it requires testing the new build again.
Draft assets require an authorized signed-in account. Published GitHub release assets are publicly downloadable. For a private mirror, download through an authorized account first; Raspberry Pi Imager cannot authenticate to a private release URL itself.
Earlier images and retained build identifiers
The earlier v1.2.0-rc.5 image
was promoted to a full release without changing its tag, filenames, embedded
version, or checksums. Its source commit is
9348aa7.
All four downloaded assets and the decompressed image were independently
checksum-checked. Its final publication lookup failed after upload; those same
audited assets were published without rebuilding or moving the tag, and the
workflow correction followed.
Do not use v1.2.0-rc.4 for fresh setup: its standalone resize boot trigger
can consume space TeslaUSB needs. It is retained only for provenance. Version
2.0.0 is a new build, not an older image renamed to remove its release label.
| Area | Upgrade | Practical benefit |
|---|---|---|
| Flashing | Native arm64/Trixie image builds with .img.xz, checksum, provenance metadata, and package manifest |
Download one verified image and flash it directly with Raspberry Pi Imager |
| First boot | Self-contained teslausb_config_wizard.html on the boot partition |
Create a conservative configuration offline without hand-editing shell code |
| Configuration | Strict teslausb_setup.json schema, type and range checks, fixed allowlist, safe migration, and secret sanitization |
Declarative JSON values are not evaluated as shell code; unsafe or incomplete values fail before setup |
| Archive reliability | SHA-256 manifests, destination verification, stable mount identity, bounded retries, and race-safe cleanup | Transfer failures are detected before source links are released |
| Dashboard and API | Responsive status UI, diagnostics, archive progress, safer file actions, and a versioned local API | Better visibility and fewer risky manual recovery steps |
| USB recovery | Manual, two-confirmation gadget repair with shared locking, cooldowns, image preflight, and post-rebuild verification | Repairs USB gadget state without silently racing archive or snapshot operations |
| Application upgrades | Content-addressed releases, checksum validation, atomic activation, health checks, automatic recovery, and rollback | A failed managed application update can return to the previous working release |
| Encrypted recordings | EncryptedClips detection and warnings with guarded snapshot, cleanup, archive, and viewer boundaries |
Opaque encrypted recordings stay outside built-in processing instead of being treated as normal clips |
| Security | Web authentication by default, same-origin POST actions, narrowed nginx/CGI/sudo boundaries, fail-closed drive selection, and pinned optional downloads | Reduces accidental exposure, command injection, and destructive-drive mistakes |
| Pi Zero 2 W safeguards | Locked image account, no embedded user credentials, verified rootwait/USB-module boot tokens, removed resize trigger, disabled resize/swap services, and exact embedded setup source |
First boot is deterministic and does not need a private GitHub token |
For the complete version-by-version record, see the
CHANGELOG.
- A Raspberry Pi Zero 2 W.
- A microSD card of at least 64 GB. A high-endurance 128 GB or larger card is recommended for more recording history and better write durability.
- A known-good USB data cable. Connect the Tesla to the Zero 2 W's USB/data (OTG) port, not its power-only port.
- A 2.4 GHz-capable Wi-Fi network with Internet access during initial setup.
- Raspberry Pi Imager.
The card sizes above are project recommendations, not Raspberry Pi hardware limits.
CAM_SIZE is the size of the virtual drive shown to the car. The card's label
uses decimal GB, but TeslaUSB's G suffix means binary GiB. Do not copy the
printed card capacity into CAM_SIZE: for example, 500G is not safe on a
512 GB card. The offline wizard asks for the advertised card capacity, enforces
the matching ceiling below, and keeps that capacity choice out of the generated
JSON.
| Capacity printed on card | Maximum CAM_SIZE |
|---|---|
| 64 GB | 40G |
| 128 GB | 100G |
| 256 GB | 210G |
| 512 GB | 440G |
| 1 TB (1000 GB) | 880G |
| 1.5 TB (1500 GB) | 1330G |
| 2 TB (2000 GB) | 1780G |
These are safety ceilings, not targets. They use the conservative rule
floor-to-10(0.90 * advertised decimal GB - 15). CAM_SIZE must be at least
20G; 40G remains the recommended starting value and leaves much more room
for filesystem metadata, copy-on-write snapshots, and normal operation. If you
configure MUSIC_SIZE, LIGHTSHOW_SIZE, BOOMBOX_SIZE, or
INCREASE_ROOT_SIZE, subtract those allocations from the table ceiling before
choosing CAM_SIZE.
The table limits storage allocation, not filesystem-check memory. Large FAT32 volumes can require more RAM to check than a Zero 2 W has available. The runtime checks an unmounted filesystem read-only first and repairs only when needed, then requires a clean verification pass. On boards with 1 GiB RAM or less it uses a temporary, bounded compressed-RAM device during the check; it does not create an SD-card swap file or enable persistent swap services. A failed live drive check stops recording startup instead of repeatedly retrying or reporting success. Do not reformat a populated card to resolve a checker-memory error.
-
Download the image and matching checksum from the same release. Version 2.0.0 testers use the authenticated draft until hardware acceptance is complete; public users should use a published image.
-
Verify the image digest before flashing. It must exactly match the digest in that image's
.img.xz.sha256file. For the version 2.0.0 image, use Windows PowerShell:Get-FileHash .\teslausb-enhanced-v2.0.0-pi-zero-2w-arm64-trixie.img.xz -Algorithm SHA256
When testing another release, use its exact downloaded filename and checksum.
-
In Raspberry Pi Imager, choose Use custom, select the downloaded
.img.xzfile directly, and write it to the card. Do not extract it first. -
Decline Raspberry Pi Imager's OS customization options. TeslaUSB uses its own first-boot configuration and the clean image contains no user Wi-Fi, archive, web, Tesla, or SSH credentials.
-
Reinsert or remount the card and open
teslausb_config_wizard.htmlfrom its boot partition in a modern browser. -
Complete the offline form and download
teslausb_setup.json. Copy it to the root of the boot partition with that exact filename; remove suffixes such as(1)that a browser may add. -
Safely eject the card, insert it into the Pi, and boot within Wi-Fi range. Initial setup downloads packages and can take longer than five minutes on a slow connection.
-
Open
http://teslausb.local/and confirm storage, network, temperature, and archive status before connecting the Pi to the car.
The one-step setup guide covers configuration choices, LED stages, troubleshooting, and what happens during first boot.
The recommended helper is teslausb_config_wizard.html, included on the
image's boot partition. It:
- runs entirely in the browser with no network requests, analytics, remote scripts, form submission, or browser storage;
- generates the web password with the browser's cryptographic random-number generator;
- redacts secrets in its on-screen review; and
- downloads only
teslausb_setup.jsonwithout scanning for or writing to a microSD card automatically.
The downloaded JSON necessarily contains your real credentials. Keep it private, retain only an encrypted backup, and remove it from shared computers.
| Setting | Recommended starting value |
|---|---|
| Camera image | CAM_SIZE: "40G" |
| Card-size safety | Enter the capacity printed on the card; keep CAM_SIZE at or below the calculated ceiling |
| Archive | ARCHIVE_SYSTEM: "none" until local operation is confirmed |
| RecentClips archive | ARCHIVE_RECENTCLIPS: false |
| Wi-Fi country | Explicit physical-location ISO country code; no default is guessed (GB, not UK) |
| Time zone | A reviewed named zone such as America/Chicago |
| Web access | Username teslausb and a unique locally generated password |
| Temperature reporting | 55 °C caution, 68 °C warning, hourly logging, and post-archive reporting |
| Destructive or external options | Leave DATA_DRIVE, access-point mode, guest Samba, notifications, and third-party WebUI downloads unset initially |
DATA_DRIVE is destructive: setup may wipe and repartition the selected
whole-disk device, and ambiguous selection fails closed. Leave it unset unless
you have independently verified the exact device.
Advanced users can use the dependency-free Node.js helper at
tools/teslausb-config.js to preflight, migrate,
generate, or sanitize configurations. See the
configuration helper guide and
declarative JSON reference.
TeslaUSB detects an EncryptedClips directory and reports a warning in the
dashboard, archive log, and local API. Built-in automation does not request
keys, decrypt, open, archive, play, move, or delete encrypted clip contents.
While encrypted recordings are detected, camera snapshots and camera-clip
archiving pause. Protected or uninspectable legacy snapshots are retained by
automatic cleanup, and literal or resolved aliases into EncryptedClips are
excluded from built-in archive and viewer paths. Independent music sync can
continue. Normal camera processing resumes after a later live check no longer
detects the directory.
This policy covers built-in automation. Arbitrary trusted root hooks remain outside that boundary. See encrypted clip detection for the exact behavior.
Web authentication is enabled by default, and state-changing actions require
same-origin POST requests. The dashboard still uses HTTP on the local
network: Basic Authentication controls access but does not encrypt traffic.
Keep TeslaUSB on a trusted private LAN or access it through a trusted VPN; do
not expose the dashboard or local API directly to the Internet.
Archive hashes and destination verification detect incomplete or changed transfers. They do not make an untrusted or compromised archive server trustworthy. Protect the archive separately with appropriate access controls, backups, and monitoring. See archive reliability.
The dashboard repair action is deliberately manual and requires two confirmations. Disconnect the Tesla or computer cleanly before using it. The repair briefly removes and rebuilds all exported drives; failed verification leaves the gadget disconnected rather than presenting an unverified device. It rebuilds the exported USB gadget only; it does not format, mount, or repair a backing image. See USB gadget repair.
The September 2026 source updates add a day-scoped viewer, Refresh recordings, snapshot/library freshness labels, and storage/clock/recovery evidence in Tools > Advanced maintenance. Refresh reads the existing index; it does not force a snapshot, disconnect USB, or make still-live footage appear immediately. Failed refreshes retain the previous library and identify it as not refreshed.
The health panel distinguishes backing-card free space from the car's virtual camera drive, which it does not inspect while recording. It shows the cleanup reserve, finalized snapshot metadata, and completed-release evidence when available. Recovery-backup allocation can include shared blocks: it is not a promise of reclaimable space, and the panel does not delete backups.
For viewer controls, cleanup-delay and independent-clock corrections, logging and connection-status semantics, and a safe on-device test plan, see runtime maintenance and verification. These changes are retained in version 2.0.0 alongside the modern interface. Publishing a release does not automatically update an installed Pi.
- Do not perform an in-place Bookworm-to-Trixie or 32-bit-to-64-bit OS upgrade. Back up the private configuration and keys, flash a clean arm64 Trixie image, and restore through the JSON configuration workflow.
- Transactional application upgrades protect the managed application release
and
/root/binentrypoints. They do not roll back OS packages, firmware, partitions, configuration, credentials, archive data, or separately managed third-party binaries. - The image contains the exact setup source needed for first boot, without an embedded GitHub credential. Public sources can be fetched anonymously; private mirrors still require an explicitly configured authenticated path. This fork does not yet provide a signed release-asset updater. Prefer a new verified image unless you have deliberately selected and verified the exact runtime update source.
See transactional upgrades for verification, recovery, rollback, and the precise transaction boundary.
Before publication, the release pipeline checks:
- MBR/FAT/ext4 layout and read-only filesystem access;
- arm64/Trixie identity and Raspberry Pi Zero 2 W boot artifacts;
- USB OTG configuration and the FAT-partition SSH marker;
- a locked default account and absence of active setup credentials;
- absence of SSH host keys, initialized machine identity, and random seed;
- the exact embedded source manifest and installed package inventory;
- removal of the standalone
resizeboot trigger, exactrootwaitand USB module tokens, and disabled resize, swap, and package-backup services; - XZ stream integrity, SHA-256 manifests, and uploaded GitHub asset digests.
Each release's matching assets include .image-metadata.json build provenance
and a .packages.tsv installed-package manifest. The build also verifies the
bundled FFmpeg tools and JPEG encoder used by recording thumbnails. Automated
checks do not replace spare-card testing; the image remains a draft until the
exact downloaded build passes hardware acceptance.
Debian and Raspberry Pi package repositories are not snapshot-pinned, so the recorded build is provenance-traceable but is not guaranteed to be bit-for-bit reproducible.
| Task | Guide |
|---|---|
| Flash and first boot | One-step setup |
| Configure or migrate safely | Configuration helper · Declarative JSON |
| Understand encrypted clips | Encrypted clip detection |
| Diagnose archive behavior | Archive reliability |
| Repair USB gadget state | USB gadget repair |
| Upgrade or roll back application files | Transactional upgrades |
| Integrate with the dashboard | Local Web API |
| Build an image from source | Pinned pi-gen recipe |
| Review every release change | Changelog |
For general TeslaUSB concepts and hardware beyond this image's primary Zero 2 W target, consult the upstream TeslaUSB wiki. Enhanced-fork defects should be reported in this repository rather than to the upstream maintainers. Sanitize configuration and diagnostic output before sharing it.
Single-board computers with USB OTG support can emulate a drive that a Tesla uses for Dashcam recordings and music. Because the computer also controls the backing storage, TeslaUSB can archive recordings when it reaches a trusted network, retain more RecentClips, expose a local viewer, and provide guarded filesystem and gadget recovery.
This community video provides a useful introduction to the original TeslaUSB architecture and installation flow. Its setup details may not match TeslaUSB Enhanced; follow the current quick start above:
The project traces back to this Reddit thread and the community-maintained upstream repository.
Pull requests and issue reports are welcome. Keep changes focused, preserve the security and fail-closed boundaries, and include relevant tests or exact reproduction steps. Never commit real TeslaUSB configuration files, passwords, tokens, private keys, VINs, or archive credentials.
Public issues and attachments can also expose Wi-Fi names, private IPs, personal paths, locations, and account details. Review and redact reports locally; share only the necessary sanitized excerpt, never a raw card image or real setup file. For sensitive security reports or an accidental credential exposure, see the security and privacy reporting guidance.
This derivative is distributed under the included MIT license. It is an independent, unofficial project and is not endorsed by or affiliated with Tesla, Inc., Raspberry Pi Ltd., or the upstream TeslaUSB maintainers. Product and project names belong to their respective owners.