Build & Ship
an Embedded Product

# Product Spec

## 1. Product Summary
Name:
One-liner:
Target user:
Primary environment: home / classroom / lab / field / desk

## 2. Problem
What problem does this solve?
Why does the problem matter?
What happens today without this device?

## 3. MVP Features
| Feature | User value | Acceptance test | Priority |
|---|---|---|---|
| | | | Must |
| | | | Must |
| | | | Should |

## 4. Out of Scope
- 
- 
- 

## 5. Operating Conditions
Power source:
Network required? yes / no
Expected runtime:
Indoor/outdoor:
Temperature or placement constraints:

## 6. Success Criteria
- 
- 
- 

## 7. Demo Criteria
In the final demo, viewers must be able to see:
- The device powering on.
- The main input or sensor working.
- The output, dashboard, notification, motion, or AI result.
- The documentation and repo structure.

# Architecture

## Hardware Blocks
- Controller board:
- Sensors:
- Actuators / outputs:
- Power source:
- Network connection:
- Enclosure / mounting:

## Software Blocks
- Main application:
- Background service:
- Dashboard / UI:
- Data storage:
- Notification path:
- Logs:

## Data Flow
Input -> Processing -> Storage -> Output

Example:
Sensor reading -> Python service -> SQLite / JSON log -> Web dashboard

## Power Flow
Power source -> regulator / board -> sensors -> actuators

## Risk Register
| Risk | Impact | Prevention | Recovery |
|---|---|---|---|
| Wi-Fi disconnects | Dashboard stops updating | Local cache | Auto reconnect / retry |
| Loose sensor wire | Bad readings | Strain relief | Error message + status LED |
| Service crashes | Product stops | systemd restart | Logs + auto restart |

# Bill of Materials

## Parts List
| Part | Qty | Purpose | Est. cost | Substitute | Notes |
|---|---:|---|---:|---|---|
| | 1 | | $ | | |
| | 1 | | $ | | |

## Tools Used
- 
- 

## Power Budget
| Component | Voltage | Estimated current | Notes |
|---|---:|---:|---|
| Controller board | | | |
| Sensor | | | |
| Motor / output | | | |

Estimated total current:
Power supply chosen:
Why this supply is safe:

## Cost Summary
Prototype cost:
Nice-to-have upgrades:
Minimum build cost:

## Purchasing Notes
Search terms:
Part links or supplier notes:
Known compatibility warnings:

embedded-product/
├── README.md
├── PRODUCT_SPEC.md
├── ARCHITECTURE.md
├── BOM.md
├── TEST_PLAN.md
├── RELEASE_CHECKLIST.md
├── config.example.json
├── setup.sh
├── src/
│   ├── main.py
│   ├── sensors.py
│   ├── outputs.py
│   └── dashboard.py
├── docs/
│   ├── wiring.md
│   ├── setup.md
│   ├── troubleshooting.md
│   └── images/
├── assets/
│   ├── thumbnail.png
│   └── demo-script.md
└── tests/
    ├── hardware-checklist.md
    └── smoke-test.md

#!/usr/bin/env bash
set -e

echo "== TeqStudy Embedded Product Setup =="

if ! command -v python3 >/dev/null 2>&1; then
  echo "Python 3 is required. Install it first."
  exit 1
fi

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

if [ -f requirements.txt ]; then
  pip install -r requirements.txt
fi

if [ ! -f config.json ] && [ -f config.example.json ]; then
  cp config.example.json config.json
  echo "Created config.json from config.example.json"
fi

echo "Running smoke test..."
python src/main.py --self-test || {
  echo "Self-test failed. Check wiring, config, and logs."
  exit 1
}

echo "Setup complete. Next: edit config.json, then run ./start.sh"

# /etc/systemd/system/teq-device.service
[Unit]
Description=TeqStudy Embedded Product Service
After=network-online.target
Wants=network-online.target

[Service]
WorkingDirectory=/home/pi/embedded-product
ExecStart=/home/pi/embedded-product/.venv/bin/python src/main.py
Restart=always
RestartSec=5
User=pi
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

# Commands
# sudo systemctl daemon-reload
# sudo systemctl enable teq-device
# sudo systemctl start teq-device
# journalctl -u teq-device -f

# Enclosure Plan

## Physical Layout
Board location:
Sensor location:
Output/display location:
Power input location:
Cable exit points:
Mounting plan:

## Safety and Reliability
Strain relief method:
Ventilation / heat plan:
Protection from shorts:
Access to reset/power:

## User-Facing Labels
- Power:
- Status LED:
- Sensor direction:
- Button behavior:

## Maintenance
How to open the enclosure:
How to replace the SD card / battery / sensor:
How to check logs:

# Test Plan

## Smoke Test
| Test | Steps | Expected result | Pass/Fail | Notes |
|---|---|---|---|---|
| Cold boot | Unplug, plug in, wait | Service starts | | |
| Main feature | Trigger input | Output appears | | |

## Hardware Tests
| Component | Test | Expected result | Pass/Fail |
|---|---|---|---|
| Sensor | | | |
| Output | | | |

## Failure Tests
| Failure | What you do | Expected recovery | Pass/Fail |
|---|---|---|---|
| Wi-Fi lost | Disconnect network | Device retries / local mode | |
| Service crash | Kill service | systemd restarts | |
| Bad config | Rename config | Clear error shown | |

## Soak Test
Start time:
End time:
Issues found:
Fixes applied:

## Demo Test
Can the final demo be completed in 90 seconds? yes / no

# Project Name

One-sentence product promise.

## What It Does
- 
- 
- 

## Demo
Screenshot or demo video link:

## Hardware Required
See BOM.md for full parts list.

## Wiring
Add diagram/photo here.

## Setup
```bash
git clone <repo-url>
cd embedded-product
chmod +x setup.sh
./setup.sh
```

## Configuration
Copy config.example.json to config.json and edit values.

## Run
```bash
python src/main.py
```

## Run on Boot
Explain service setup or link to docs/setup.md.

## Testing
See TEST_PLAN.md.

## Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| Device does not boot | Power supply issue | Use rated supply |
| No sensor data | Wiring/config | Check wiring.md |

## Future Improvements
- 
- 

## Credits / License

# Demo Script

## Product Name

## 0-10 sec: Problem
This device helps [user] solve [problem] by [promise].

## 10-30 sec: Hardware Tour
Controller:
Sensors:
Outputs:
Power:

## 30-65 sec: Live Demo
Action I will trigger:
Expected device behavior:
What viewers should watch for:

## 65-80 sec: Productization Proof
Show README / BOM / test plan / service logs.

## 80-90 sec: Next Step
If I had another week, I would improve:

## Assets Needed
- thumbnail image
- wiring photo
- dashboard screenshot
- short demo video
- GitHub repo link

# Release Checklist

## Product Files
- [ ] README.md complete
- [ ] PRODUCT_SPEC.md complete
- [ ] ARCHITECTURE.md complete
- [ ] BOM.md complete
- [ ] TEST_PLAN.md complete
- [ ] ENCLOSURE_PLAN.md complete
- [ ] DEMO_SCRIPT.md complete
- [ ] config.example.json included
- [ ] setup.sh tested
- [ ] no secrets committed

## Device Checks
- [ ] cold boot passes
- [ ] main feature passes
- [ ] logs are readable
- [ ] bad config produces clear error
- [ ] network loss behavior tested
- [ ] enclosure/wiring is safe enough for demo

## Portfolio Checks
- [ ] thumbnail added
- [ ] screenshots added
- [ ] demo video recorded
- [ ] GitHub description updated
- [ ] resume bullet written

## Final Reflection
What worked:
What failed:
What you fixed:
What you would build next: