Kittcat

Kittcat — Automated bag handling (prototype)

A compact description and quick-start for the project. This README is intentionally high-level: it documents what the project does, how to build and run it, the file structure, and a few troubleshooting pointers — without duplicating implementation details from the source.

Overview

• Purpose: coordinate servos and a solenoid to pick up a bag, accept an inserted item, and release/restart.
• Behavior: a small state machine runs a fixed sequence (pick up, wait for insert, close valve, wait for retrieval, restart).

Quick start

1. Install PlatformIO (VS Code extension or CLI).
2. Connect your board and a regulated 5V supply for actuators (share grounds).
3. From the project root:

platformio run          # build
platformio run --target upload  # upload
platformio device monitor       # open serial monitor

File structure

• platformio.ini — build configuration
• src/main.cpp — state machine and system glue
• include/ — project headers
• src/actuators/ — actuator implementations (servos, solenoid, etc.)
• src/sensors/ — sensor drivers
• test/ — tests and quick experiments

Usage notes

• Power: use an external 5V supply for servos/solenoid. Always connect the external supply ground to the board ground.
• Serial: use the serial monitor for debug output; reduce verbosity if logging affects timing.
• Sensors: the code polls the distance sensor continuously during the insert/retrieve stages — that polling is intentional and required.

Troubleshooting (concise)

• Glitches or resets: usually caused by power (voltage sag) or current spikes. Move servos/solenoid to a stronger supply.
• Unexpected sensor readings: ensure grounds are common and check sensor VCC/GND polarity. Many light-gate modules are active-LOW.
• Timer/library conflicts: if actuators or sensors use timers, try alternate libraries or restructure code to avoid conflicts.

How to extend

• Add more servos: the project includes a small multi-servo helper; create additional ServoMotor instances.
• Smooth motion: implement ramped moves (small steps with short delays) to reduce peak current.
• Persistence: store counters/state in EEPROM if you need to survive power cycles.