Skip to content
This repository was archived by the owner on Apr 10, 2026. It is now read-only.

MISSIONS.md

Latest commit

 

History

History
176 lines (130 loc) · 8.14 KB

MISSIONS.md

File metadata and controls

176 lines (130 loc) · 8.14 KB

ERIC — Mission System

← Back to README

Missions are YAML files in the missions/ folder. Drop a new .yaml file in, click ↺ refresh in the GUI, and it appears instantly. No code required. Cosmos reads the briefing as plain English — no structured format needed.

How It Works

When you press ENGAGE:

  1. Cosmos parses the briefing into an ordered list of MissionStep objects — targets, sequencing, and action types extracted from natural language
  2. KV cache warm-up fires a tiny pre-fill request so all subsequent Cosmos calls this mission pay only the incremental token cost
  3. Eric executes steps sequentially — advancing only when each one is confirmed complete
  4. The alarm_type field controls what fires on a find — LED pattern, audio tone, TTS prefix, follow-on behaviour
  5. At mission end, _mission_report() delivers a summary of all finds

Multi-Step Example

Briefing: "First find the security guard and speak to him. Then find the manager and wait for
           their response. Finally, locate the exit and photograph it."

→ Step 1 of 3: target=security guard  action=speak_to
→ Step 2 of 3: target=manager         action=wait_for_response
→ Step 3 of 3: target=exit            action=photograph

Eric will not advance to Step 2 until Step 1 is complete.

YAML Schema

# Required
name: "Mission Name"
briefing: |
  Your full mission briefing here. Cosmos reads every word.
  Write it like you're briefing a human agent.

# Recommended
description: "One line for logs and README"
author: "Your name"

# Alarm type — controls what fires when a target is found
alarm_type: none   # none | hazard | siren | suspicious | nature

# What Cosmos watches for in every frame
target_objects:
  - person
  - robot

# Behaviour on find
photo_on_find:     false  # save timestamped photo to missions/photos/ (dual-cam, blur-checked)
announce_location: false  # TTS location announcement (nature missions: respects wildlife)
stay_with_target:  false  # SAR: stay and repeat broadcast every 15s
back_away_on_find: false  # security: back 3m + turn 180°
generate_report:   false  # mission end: summary of all finds

# 360° scan strategy — controls which scan mode Eric uses
scan_strategy: target_hunt   # target_hunt (default) | video_sweep
# target_hunt: async per-position pan-tilt sweep, early-exit on first confirmed target
#              Best for: search & rescue, find missions, security
# video_sweep: continuous chassis rotation + single panoramic video inference, no early-exit
#              Best for: nature explorer, inspection, patrol, survey

# Approach behaviour
approach_distance: 0.65   # metres — OAK-D/YOLO distance threshold for "arrived" (default 0.65m)
approach_on_detect: true  # YOLO: approach on detection (false = report only, stay in place)
detect_distance: 2.0      # metres — YOLO distance above which Eric steers toward (not stops)

# Obstacle circumnavigation (experimental)
circumnavigate_on_empty: false   # peek around blocking obstacle before doing full 360
circum_step_sec: 1.8             # seconds to side-step (tune for room size)
circum_dist_m: 0.4               # estimated step distance in metres
circum_forward_sec: 0.0          # optional forward nudge before side-stepping

# Narrative mission behaviour
wait_for_dismiss: false   # stay in place after greeting until operator presses STOP

# Characters (played by operator in GUI)
characters:
  - name: "Security Guard"
    hint: "Knows the building layout. Will share info if approached politely."

# Stage-by-stage goals — Cosmos sees the current stage goal during that step
mission_stages:
  - goal: "Find the security guard and ask about the building layout"
  - goal: "Find the manager and deliver the message"
  - goal: "Locate the exit and confirm it is clear"

# Terrain Eric will encounter (affects speed)
terrain:
  - "Smooth tile (normal speed)"
  - "Carpet (slow down)"

# GM notes — Eric ignores this section entirely
notes: |
  Setup: place the security guard near the entrance, manager in the back office.
  Character scripts: guard is friendly but cautious until asked directly.

Action Types

Action What happens
find_and_approach Navigate to target, mark done on arrival
deliver_message Speak message to target, wait wait_sec seconds, advance
speak_to Greet + initiate conversation, wait wait_sec seconds for operator to type reply
wait_for_response Stop and wait wait_sec seconds — operator types character reply in GUI
photograph Capture photo_count sharp blur-checked photos to missions/photos/

Alarm Types

Alarm LED Audio TTS Prefix Follow-on
siren Rapid red strobe Rising oscillating tone "EMERGENCY! EMERGENCY!" Stay with target, repeat every 15s (if stay_with_target: true)
hazard Slow amber pulse Triple warning beep "WARNING! HAZARD DETECTED!" Log severity (CRITICAL/WARNING/ADVISORY), continue patrol
suspicious Medium red strobe Urgent staccato beeps "ALERT! SUSPICIOUS OBJECT!" Back away 3m, turn 180°, hold (if back_away_on_find: true)
nature Gentle green pulse None (no prefix — just narration) Photograph, narrate, continue
none None None None Find-and-approach → confirm description → eye contact → greet → photograph

All alarm tones are generated mathematically at runtime (raw PCM via struct.pack) — no audio files, no internet required.

Narrative Missions (alarm_type: none)

With alarm_type: none, Eric runs the full target confirmation pipeline on arrival:

  1. Cosmos checks if the person matches the description in the characters hints
  2. If description doesn't match: Eric asks the stranger for directions, then resumes search
  3. If it matches: tilt sweep to find face → eye contact gate → greet → dual-cam photos
  4. If wait_for_dismiss: true: Eric stays in place after greeting until operator presses STOP

The characters list provides Cosmos with description hints for identity checking. The owner keyword in a character name triggers the description-match logic (e.g. name: "Creator / Owner").

Mission Library

File Name Alarm Scan Description
search_and_rescue.yaml Search and Rescue 🚨 siren target_hunt Find injured person, sound siren, stay and broadcast
greet_owner.yaml Greet the Owner none target_hunt Find creator by description, wait for eye contact, greet
room_safety_check.yaml Room Safety Check ⚠️ hazard video_sweep Full-room audit — PASS / CONDITIONAL PASS / FAIL
nature_exploring.yaml Nature Exploring 🌿 nature video_sweep Wildlife + plants — poetic narration, photo each find
msg_for_contact.yaml Deliver Message none target_hunt Find a specific person and deliver a message
find_SD_card.yaml Operation Lost Card none target_hunt Systematic office sweep to find a missing SD card

Writing Your Own Mission

  1. Copy missions/template.yaml
  2. Write your briefing in plain English — Cosmos reads it as-is
  3. Set alarm_type to match what Eric should do on a find
  4. Set scan_strategy: video_sweep if this is an observation/patrol mission; leave default for find missions
  5. Add characters with hint so you know what to type during the demo
  6. Add mission_stages if you want Cosmos to have a focused sub-goal per step
  7. Click ↺ refresh in the GUI — your mission appears in the dropdown immediately

Tips

  • Multi-step missions: write the briefing in sequence ("First find X. Then find Y. Finally..."). Cosmos will parse the steps automatically.
  • Find-and-greet (alarm_type: none): add a character with name: "Creator / Owner" and a physical description in hint. Eric will check the description before greeting.
  • Observation missions: set scan_strategy: video_sweep — Eric sweeps the whole room in one continuous rotation and sends the panoramic video to Cosmos.
  • Circumnavigation: add circumnavigate_on_empty: true if your target might be hidden behind a box. Eric will peek around obstacles before doing a full 360.