Tracking PetTracer location (and generating map screenshots)

Why this skill exists

PetTracer collar tracking is exposed via an unofficial web portal API and a SockJS/STOMP WebSocket. This skill provides a reliable, repeatable workflow to:

• Get a pet’s latest known location (REST snapshot)
• Fetch location history for a time window
• Subscribe to live updates (WebSocket)
• Generate a map screenshot image (PNG) you can send to the user

Quick start

1) Set credentials (preferred)

export PETTRACER_USERNAME="you@example.com"
export PETTRACER_PASSWORD="…"

2) (For map screenshots) Set Google Maps Static API key

export GOOGLE_MAPS_API_KEY="…"

3) Get the latest location (JSON)

python scripts/pettracer_cli.py locate --pet "Fluffy" --pretty

4) Generate a map screenshot PNG for the latest location

python scripts/pettracer_mapshot.py --pet "Fluffy" --pretty
# → writes a PNG under ./output/ and prints JSON with the file path

Capabilities

Snapshot (latest fix)

• scripts/pettracer_cli.py locate — latest known lat/lon + timestamps + battery + helpful links

History (time window)

• scripts/pettracer_cli.py history — list of points for the last N hours or an explicit time range

Live tracking

• scripts/pettracer_watch.py — NDJSON stream of live updates via SockJS/STOMP

Map screenshot (PNG)

• scripts/pettracer_mapshot.py — downloads a static map image centred on the latest fix

See: references/maps.md

Required inputs

PetTracer auth (choose one)

Option A (preferred):

• PETTRACER_USERNAME (or PETTRACER_EMAIL)
• PETTRACER_PASSWORD

Option B:

• PETTRACER_TOKEN (bearer token)

Maps auth (for screenshots)

• GOOGLE_MAPS_API_KEY

Optional tuning:

• GOOGLE_MAPS_MAPTYPE (hybrid default)
• GOOGLE_MAPS_SIZE (640x640 default)
• GOOGLE_MAPS_SCALE (2 default)

Core workflow (agent)

1. Decide what the user wants:

   • “Where is my pet right now?” → snapshot (locate)
   • “Where has my pet been today?” → history (history)
   • “Track live for 5 minutes” → live (pettracer_watch.py)
   • “Send me a screenshot/map image” → map screenshot (pettracer_mapshot.py)

2. Resolve which device:

   • If user names the pet → pass --pet "Name"
   • If ambiguous/multiple devices → run list and pick by id or exact name match

3. Run the smallest command that answers the request.

4. Validate freshness:

   • Use last_fix_age_s to decide whether the fix is stale.
   • If stale or missing: say so plainly; provide last_contact and suggest switching collar mode in the official app.

5. If user asked for a map screenshot:

   • Run pettracer_mapshot.py.
   • Attach/send the generated PNG.
   • Also include the interactive map link for convenience.

Commands

List devices

python scripts/pettracer_cli.py list --pretty

Locate a pet

python scripts/pettracer_cli.py locate --pet "Fluffy" --pretty

# If multiple devices, disambiguate:
python scripts/pettracer_cli.py locate --device-id 12345 --pretty

Location history

# last 6 hours (default)
python scripts/pettracer_cli.py history --pet "Fluffy" --pretty

# last 24 hours
python scripts/pettracer_cli.py history --pet "Fluffy" --hours 24 --pretty

# explicit window (epoch ms)
python scripts/pettracer_cli.py history --device-id 12345 --from-ms 1767152926491 --to-ms 1767174526491 --pretty

Live updates (NDJSON)

# Install dependency
pip install -r scripts/requirements.txt

# Stream updates
python scripts/pettracer_watch.py --pet "Fluffy"

Map screenshot (PNG)

# Writes ./output/pettracer_<pet>_<id>_<ts>.png
python scripts/pettracer_mapshot.py --pet "Fluffy" --pretty

# Choose output path
python scripts/pettracer_mapshot.py --pet "Fluffy" --out output/fluffy_latest.png --pretty

# Tune map appearance
GOOGLE_MAPS_MAPTYPE=satellite python scripts/pettracer_mapshot.py --pet "Fluffy" --zoom 18 --pretty

Present results consistently

When answering the user, prefer:

• Human summary: “Latest fix at HH:MM, accuracy ~X m, battery ~Y%.”
• Freshness: say if stale: “Fix is ~N minutes old.”
• Map link(s): include the google_maps and openstreetmap links.
• If map screenshot requested: send/attach the PNG generated by pettracer_mapshot.py.

Security / privacy rules

• Never paste PETTRACER_PASSWORD, PETTRACER_TOKEN, or GOOGLE_MAPS_API_KEY into chat.
• Avoid printing URLs that contain secrets (PetTracer WebSocket URLs include access_token=…).
• If you must log, redact secrets.

Reference files

• PetTracer REST endpoints: references/endpoints.md
• Data model fields: references/data-model.md
• Tracking modes (heuristics): references/modes.md
• WebSocket protocol notes: references/websocket.md
• Map screenshots: references/maps.md

THE EXACT PROMPT — “Send me a map screenshot”

1) Run pettracer_mapshot.py for the requested pet/device.
2) If it returns no_recent_fix, explain that and include last_contact.
3) If it returns an image path, attach/send that PNG to the user.
4) In the message: include timestamp, fix age, accuracy, and a clickable Google Maps link.
5) Do not reveal any API keys/tokens.