239 lines
9.2 KiB
Markdown
239 lines
9.2 KiB
Markdown
# My Tesla
|
||
|
||
Tesla control skill for Clawdbot.
|
||
|
||
Author: Parth Maniar — [@officialpm](https://github.com/officialpm)
|
||
|
||
## What’s inside
|
||
|
||
- `SKILL.md` — the skill instructions
|
||
- `scripts/tesla.py` — the CLI implementation (teslapy)
|
||
- `VERSION` + `CHANGELOG.md` — versioning for ClawdHub publishing
|
||
|
||
## Install / auth
|
||
|
||
Set `TESLA_EMAIL` and run:
|
||
|
||
```bash
|
||
TESLA_EMAIL="you@email.com" python3 scripts/tesla.py auth
|
||
```
|
||
|
||
This uses a browser-based login flow and stores tokens locally in `~/.tesla_cache.json` (best-effort chmod `0600`).
|
||
|
||
Optional defaults:
|
||
- `MY_TESLA_DEFAULT_CAR` — default vehicle display name (overrides `default-car` setting)
|
||
- `python3 scripts/tesla.py default-car "Name"` stores a local default in `~/.my_tesla.json` (best-effort chmod `0600`)
|
||
|
||
## Usage
|
||
|
||
```bash
|
||
# List vehicles (shows which one is default)
|
||
python3 scripts/tesla.py list
|
||
python3 scripts/tesla.py list --json # machine-readable, privacy-safe
|
||
|
||
# Version
|
||
python3 scripts/tesla.py version
|
||
python3 scripts/tesla.py --version
|
||
|
||
# Debugging
|
||
# If something fails unexpectedly, add --debug for a full traceback
|
||
# (or set MY_TESLA_DEBUG=1)
|
||
python3 scripts/tesla.py --debug status --no-wake
|
||
|
||
# Pick a car (optional)
|
||
# --car accepts: exact name, partial name (substring match), or a 1-based index from `list`
|
||
python3 scripts/tesla.py --car "Model" report
|
||
python3 scripts/tesla.py --car 1 status
|
||
|
||
# Set default car (used when you don't pass --car)
|
||
python3 scripts/tesla.py default-car "My Model 3"
|
||
|
||
# One-line summary (best for chat)
|
||
python3 scripts/tesla.py summary
|
||
python3 scripts/tesla.py summary --no-wake # don't wake a sleeping car
|
||
|
||
# Summary as JSON (privacy-safe)
|
||
# Unlike `status --json`, this emits a small sanitized object (no location).
|
||
# Includes `usable_level_percent` when the vehicle reports it.
|
||
python3 scripts/tesla.py summary --json
|
||
python3 scripts/tesla.py summary --json --raw-json # raw vehicle_data (may include location)
|
||
|
||
# One-screen report (chat friendly, more detail)
|
||
# Includes battery/charging/climate + charge port/cable + (when available) TPMS tire pressures.
|
||
# Includes "Usable battery" when the vehicle reports it (helpful for health/degradation).
|
||
# Also includes a quick openings summary (doors/trunk/frunk/windows) when the vehicle reports it.
|
||
# When available, includes a compact seat heater summary line.
|
||
# When actively charging, also shows charging power details when available (kW / V / A).
|
||
# When the vehicle reports it, includes scheduled departure / preconditioning / off-peak charging status.
|
||
python3 scripts/tesla.py report
|
||
python3 scripts/tesla.py report --no-wake
|
||
|
||
# Detailed status
|
||
python3 scripts/tesla.py status
|
||
python3 scripts/tesla.py status --no-wake
|
||
python3 scripts/tesla.py status --summary # include one-line summary + detailed output
|
||
|
||
# JSON output (prints ONLY JSON; good for piping/parsing)
|
||
# NOTE: `status --json` outputs *raw* `vehicle_data`, which may include location/drive_state.
|
||
# Prefer `summary --json` (sanitized) or `report --json` (sanitized) unless you explicitly need the raw payload.
|
||
python3 scripts/tesla.py summary --json # sanitized summary object (no location)
|
||
python3 scripts/tesla.py report --json # sanitized report object (no location)
|
||
python3 scripts/tesla.py status --json # raw vehicle_data (may include location)
|
||
python3 scripts/tesla.py report --json --raw-json # raw vehicle_data (may include location)
|
||
python3 scripts/tesla.py summary --json --raw-json # raw vehicle_data (may include location)
|
||
python3 scripts/tesla.py charge status --json # includes usable battery + (when charging) power details (kW/V/A)
|
||
|
||
python3 scripts/tesla.py --car "My Model 3" lock
|
||
# Climate (status is read-only)
|
||
python3 scripts/tesla.py climate status
|
||
python3 scripts/tesla.py climate status --no-wake
|
||
python3 scripts/tesla.py climate on
|
||
python3 scripts/tesla.py climate off
|
||
python3 scripts/tesla.py climate defrost on
|
||
python3 scripts/tesla.py climate defrost off
|
||
python3 scripts/tesla.py climate temp 72 # default: °F
|
||
python3 scripts/tesla.py climate temp 22 --celsius
|
||
python3 scripts/tesla.py charge limit 80 --yes # 50–100
|
||
python3 scripts/tesla.py charge amps 16 --yes # 1–48 (conservative guardrail)
|
||
|
||
# Scheduled charging (set/off are safety gated)
|
||
python3 scripts/tesla.py scheduled-charging status
|
||
python3 scripts/tesla.py scheduled-charging set 23:30 --yes
|
||
python3 scripts/tesla.py scheduled-charging off --yes
|
||
|
||
# Scheduled departure (read-only)
|
||
python3 scripts/tesla.py scheduled-departure status
|
||
python3 scripts/tesla.py scheduled-departure status --no-wake
|
||
python3 scripts/tesla.py --json scheduled-departure status
|
||
|
||
# Trunk / frunk (safety gated)
|
||
python3 scripts/tesla.py trunk trunk --yes
|
||
python3 scripts/tesla.py trunk frunk --yes
|
||
|
||
# Windows
|
||
python3 scripts/tesla.py windows status
|
||
python3 scripts/tesla.py windows status --no-wake
|
||
python3 scripts/tesla.py windows status --json
|
||
|
||
# Windows (safety gated)
|
||
python3 scripts/tesla.py windows vent --yes
|
||
python3 scripts/tesla.py windows close --yes
|
||
|
||
# Seat heaters
|
||
python3 scripts/tesla.py seats status
|
||
python3 scripts/tesla.py seats status --no-wake
|
||
python3 scripts/tesla.py seats status --json
|
||
|
||
# Seat heaters (safety gated)
|
||
# seat: driver|passenger|rear-left|rear-center|rear-right|3rd-left|3rd-right (or 0–6)
|
||
# level: 0–3 (0=off)
|
||
python3 scripts/tesla.py seats set driver 3 --yes
|
||
|
||
# Charge port door
|
||
python3 scripts/tesla.py charge-port status
|
||
python3 scripts/tesla.py charge-port status --no-wake
|
||
python3 scripts/tesla.py charge-port status --json
|
||
|
||
# Charge port door open/close (safety gated)
|
||
python3 scripts/tesla.py charge-port open --yes
|
||
python3 scripts/tesla.py charge-port close --yes
|
||
|
||
# Sentry Mode (status is read-only; on/off safety gated)
|
||
python3 scripts/tesla.py sentry status
|
||
python3 scripts/tesla.py sentry status --no-wake
|
||
python3 scripts/tesla.py sentry on --yes
|
||
python3 scripts/tesla.py sentry off --yes
|
||
|
||
# Location (approx by default; use --yes for precise coordinates)
|
||
python3 scripts/tesla.py location
|
||
python3 scripts/tesla.py location --no-wake
|
||
python3 scripts/tesla.py location --digits 1 # coarser rounding
|
||
python3 scripts/tesla.py location --digits 3 # a bit more precise (still approximate)
|
||
python3 scripts/tesla.py location --yes
|
||
|
||
# Tire pressures (TPMS)
|
||
python3 scripts/tesla.py tires
|
||
python3 scripts/tesla.py tires --no-wake
|
||
|
||
# Openings (doors/trunks/windows)
|
||
python3 scripts/tesla.py openings
|
||
python3 scripts/tesla.py openings --no-wake
|
||
python3 scripts/tesla.py openings --json
|
||
|
||
# Mileage tracking (odometer) — local SQLite
|
||
python3 scripts/tesla.py mileage init
|
||
python3 scripts/tesla.py mileage record --no-wake --auto-wake-after-hours 24
|
||
python3 scripts/tesla.py mileage status
|
||
python3 scripts/tesla.py mileage export --format csv > mileage.csv
|
||
python3 scripts/tesla.py mileage export --format json > mileage.json
|
||
|
||
# Export a time window
|
||
python3 scripts/tesla.py mileage export --format csv --since-days 7 > mileage_last_7d.csv
|
||
python3 scripts/tesla.py mileage export --format json --since-ts 1738195200 > mileage_since_ts.json
|
||
```
|
||
|
||
## Mileage tracking (hourly)
|
||
|
||
This feature records each vehicle’s **odometer miles** to a **local SQLite database** so we can build analytics later.
|
||
|
||
Defaults:
|
||
- DB path: `~/.my_tesla/mileage.sqlite` (override with `MY_TESLA_MILEAGE_DB` or `mileage --db ...`)
|
||
- Wake behavior: **no wake by default**. The recorder will only allow waking a car **if it hasn’t recorded mileage in 24h**.
|
||
|
||
### Quick start
|
||
```bash
|
||
python3 scripts/tesla.py mileage init
|
||
python3 scripts/tesla.py mileage record --no-wake --auto-wake-after-hours 24
|
||
python3 scripts/tesla.py mileage status
|
||
```
|
||
|
||
### Run every hour (macOS launchd example)
|
||
Create `~/Library/LaunchAgents/com.mytesla.mileage.plist`:
|
||
```xml
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||
<plist version="1.0">
|
||
<dict>
|
||
<key>Label</key><string>com.mytesla.mileage</string>
|
||
<key>StartInterval</key><integer>3600</integer>
|
||
<key>ProgramArguments</key>
|
||
<array>
|
||
<string>/usr/bin/python3</string>
|
||
<string>/ABS/PATH/TO/scripts/tesla.py</string>
|
||
<string>mileage</string>
|
||
<string>record</string>
|
||
<string>--no-wake</string>
|
||
<string>--auto-wake-after-hours</string><string>24</string>
|
||
<string>--json</string>
|
||
</array>
|
||
<key>EnvironmentVariables</key>
|
||
<dict>
|
||
<key>TESLA_EMAIL</key><string>you@email.com</string>
|
||
</dict>
|
||
<key>StandardOutPath</key><string>~/.my_tesla/mileage.log</string>
|
||
<key>StandardErrorPath</key><string>~/.my_tesla/mileage.err.log</string>
|
||
</dict>
|
||
</plist>
|
||
```
|
||
Load it:
|
||
```bash
|
||
launchctl load -w ~/Library/LaunchAgents/com.mytesla.mileage.plist
|
||
```
|
||
|
||
## Tests
|
||
|
||
```bash
|
||
# (Recommended) avoid writing __pycache__/ bytecode files into the repo
|
||
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
|
||
|
||
# Or use the helper (cleans stray bytecode first and fails if any is produced):
|
||
./scripts/run_tests.sh
|
||
```
|
||
|
||
## Privacy / safety
|
||
|
||
- Never commit tokens, VINs, or location outputs.
|
||
- Some commands (unlock/charge start|stop|limit|amps/trunk/windows/seats set/sentry on|off/honk/flash/charge-port open|close/scheduled-charging set|off) require `--yes`.
|
||
- Read-only commands support `--no-wake` to avoid waking the car (will fail if the vehicle is asleep/offline).
|
||
- `location` shows *approximate* coords by default; add `--yes` for precise coordinates.
|