City Parcel Locker

Picture a parcel locker bank on your Learning Group's city tile. Users select a bay, a servo door opens, occupancy LEDs show free vs occupied, and an OLED guides the interaction. Presence sensing (PIR/ultrasonic) can confirm someone is at the locker. At least two lockers give enough depth for two sprints. That is embedded logic: selection input and presence drive coordinated doors, lights, and messages.

In this challenge you design and build a city parcel locker for your Learning Group city tile: select among at least two bays, open/close servo doors, show occupied/free, and expose bay status to full-stack. Because this challenge spans two sprints, the delivered result is a multi-bay system — not a single servo with one LED. You integrate into the city’s shared firmware, make sensor data and controls available to full-stack classmates, and work through research, advice, design, and realisation for your Sprint 1-2 Learning Goal. Follow the city Requirements.

Your Learning Goal title in Portflow

Use: Sprint 1-2 - Learning Goal - City Parcel Locker (adjust the sprint number if needed). See the Learning Goal page for the Portflow template.

Illustration

The animation below shows the idea in simplified form (bay select, door opens, occupancy). Your delivered system must cover at least two lockers — each with door, occupancy indication, and clear free/occupied states.

Challenge

Your Learning Group city needs a multi-bay city parcel locker on a city tile. Users select a bay (buttons), a servo door opens/closes, occupancy LEDs and OLED messages show free vs occupied, and optional PIR/ultrasonic confirms presence. Your work is part of one shared embedded firmware for the city — not a separate personal project.

You will deliver a working prototype and the documents that justify and explain it. Work in this order:

Understand the problem. How many bays (at least two)? How does the user select a bay? When is a bay free vs occupied? When may a door open? Write clear rules, e.g. “Only the selected free bay may open; after timeout the door closes and bay becomes occupied if a parcel was ‘deposited’.” Agree which tile template you use and how this challenge fits the city plan.
Research. Compare realistic ways to select bays, drive multiple servo doors, track occupied/free, and sense presence, plus how to expose bay status to full-stack. Use datasheets and cite resources for decisions.
Advise. Recommend one architecture: microcontroller role in the shared city firmware, doors and indicators per bay, selection UX, and the data/control interface for full-stack. State what you are not building in this period.
Design. Specify hardware (wiring, pin map, BOM) and software (state machine for multiple bays, open/close, occupied/free, interface messages) so someone else could rebuild your system and integrate it into the shared firmware.
Realise. Build and test in small steps. Prefer separate Arduino sketches for parts (one door, one LED, OLED text, buttons, then second bay, then coordination) before you merge working pieces into the shared city firmware on GitLab main. Keep each test sketch tiny. Then demonstrate: select bay A vs B, open/close, occupied/free states, and interface messages. Use simulation or stubs if full-stack or other tiles are not ready yet — do not wait on classmates to progress.

Minimum scope (Sprint 1–2)

Your contribution must include:

Ownership of one city tile based on a LightBurn template, with the locker bank placed on that tile (or a clear bench stand-in while the tile is cut).
Integration into the city’s one shared embedded firmware (follow the city’s code conventions; do not ship a parallel personal firmware stack).
A microcontroller (e.g. ESP32-class board) that runs that shared firmware with your multi-bay locker behaviour included.
Control of at least two locker bays. For each bay you control:
- A servo door (SG90 or similar),
- An occupancy LED (free vs occupied colours, or on/off with documented meaning),
- Clear open/close and occupied/free states in firmware.
Shared interaction hardware:
- Buttons to select bay (one per bay, or a select + confirm scheme you document),
- An OLED for user messages (e.g. “Select bay”, “Bay 1 open”, “Bay 2 occupied”),
- Optional but recommended: PIR or ultrasonic presence so the locker knows someone is standing in front.
Firmware that coordinates selection, doors, and occupancy. Example pattern:
- Idle: both doors closed; LEDs show free/occupied; OLED prompts select,
- User selects free bay A → door A opens; after timeout door closes and bay A becomes occupied (or stays free if you model “pickup” separately — document one clear model),
- Selecting an occupied bay shows a refuse message unless you implement a pickup flow.
A documented state sequence for deposit and/or pickup. Keep it simple and explain your choice (one flow is enough; both deposit and pickup is recommended if time allows).
Debouncing on buttons and timeouts so doors cannot stay open forever.
A documented data and control interface for full-stack developers: bay status (free/occupied, door open/closed) per bay, plus commands that can reserve, open, or mark empty (message names, payload fields, and an example). Full-stack may connect later — you still define and demo the interface (Serial, MQTT, or another city-agreed protocol), with simulation if needed.
Updates to the city’s shared BOM and wiring diagram for your hardware.

Recommended scope

If you have time, add one or more of:

A third bay with the same rules.
Explicit deposit and pickup flows (occupied → open → free).
Serial debug output showing selection and per-bay state.
A simple locker model (cardboard bays) so doors are obvious in demos.
A stub or simulator feed that full-stack can use before your hardware is on the desk.

Out of scope for this challenge

These are not part of this challenge:

Real parcel-carrier APIs, payments, or cryptographic locker credentials.
Computer vision / ML package recognition.
Production metal lockers or certified access control.
Building the city back-end, front-end, or Raspberry Pi stack yourself — that is full-stack work. You do define and expose the embedded interface they connect to.
A separate personal firmware repo that never merges into the city’s shared embedded application.

Demo and safety context

Treat the prototype as lab equipment, not a real locker network:

Default doors closed when idle; never leave a bay unmarked (always free or occupied).
Predictable rules. Document exactly when a door may open and when occupancy flips.
Clear demo script. Anyone in your Learning Group can show at least: select free bay A → open/close → occupied; refuse or pickup on occupied; bay B independent; interface reports both bays.
Independent progress. You can demo your tile and interface with simulation or stubs while classmates finish their parts.

Starting points

Use these concrete first steps early in Sprint 1:

Read the city Requirements and agree your challenge with the Learning Group (no duplicate challenges).
Pick your tile template and sketch two bays, doors, LEDs, buttons, OLED, optional presence sensor.
Agree on multi-bay rules. For each bay: when may it open, and when does occupied/free change? Write rules in plain language.
Inventory hardware. List what your studio kit provides (ESP32, two servos, LEDs, buttons, OLED, breadboard, optional PIR/ultrasonic). Note gaps early and ask your coach. Start the city’s shared BOM. Optional KY modules from coach stock are fine if documented.
Test in small sketches first. Create short Arduino sketches for one concern at a time (e.g. one servo door, one LED, OLED messages, buttons, then second bay). Do not develop everything only inside the city’s main shared firmware.
Blink one LED to confirm toolchain: IDE, upload, Serial.begin, one GPIO. See First ESP32 project.
Draft the full-stack interface with your city (per-bay status topics/messages and open/reserve commands). Agree a simulation path so neither side waits. Prove the messages in a small sketch before wiring them into shared firmware.
Draft your research question. Example: Which bay selection UX, door actuators, and occupancy model best fit a multi-bay locker tile given GPIO limits and full-stack integration?
Create your Learning Goal in Portflow. Link the product deliverables you plan to submit. Follow Learning Goal.
Integrate only what works. Prove bay A in sketches, then bay B, then selection coordination; move proven behaviour into the shared firmware in small merges.

Suggested sprint timeline

The Learning Group does not use Scrum, but you still follow the sprint rhythm of the Group Project: two sprints for this challenge (Sprint 1-2).

In the first sprint you focus on research and advice (including the multi-bay concept) and prove one bay in small sketches. In the second sprint you focus on design and realisation of the full multi-bay system: second bay, selection UX, shared-firmware integration, and the full-stack interface.

Sprint	Focus	Outcome
1	Research & advise (+ first bay in sketches)	Research report; advisory report; tile and bays chosen; open/occupied rules; hardware choice; draft per-bay data/control interface; one bay proven in a small test sketch
2	Design & realisation (multi-bay)	Wiring diagram + pin map + multi-bay state diagram; shared BOM updated; at least two bays coordinated in shared firmware on city GitLab `main`; demo of both bays (with simulation if needed); Portflow evidence linked; reflection

Tools, frameworks, and hardware

Area	Suggestions
City tile	One of the five LightBurn templates
Microcontroller	ESP32 / ESP32-S3 / ESP32-C3 (align with city hardware choices)
Actuators	SG90 servo per bay; LEDs + resistors for occupancy
Display	OLED for user messages
Sensors / input	Buttons for bay select; optional PIR or ultrasonic presence; optional buzzer for refuse/error
IDE	Arduino IDE or PlatformIO
Version control	City GitLab project, shared firmware on `main`
Documentation	Markdown on the city MkDocs site and in the repo (English); cite sources for decisions
Full-stack link	Documented messages (Serial, MQTT, or city-agreed protocol); stubs/simulation so you do not block each other

Profile knowledge worth revisiting:

Products

Your challenge evidence is a set of products: studio deliverables tied to learning outcomes. Submit them in Portflow and link them from your Learning Goal.

Analyse & Advise

Product	What you deliver	Template
Research	Analysis of multi-bay selection, door control, and occupancy signalling; comparison with criteria; recommendation for design	Research product
Advice	Decision document: chosen MCU role in shared firmware, doors and indicators per bay, occupied/free model, full-stack data/control interface, and implementation order (one bay → second bay → coordination)	Advisory report

Suggested titles for Portflow

Research: Multi-bay selection and occupancy for city parcel locker
Advice: Coordinated multi-bay parcel locker architecture

The advice report should build on the research report. Do not repeat the full comparison tables.

Design & Realise

Product pages for design and realisation are still being added to the studio catalogue. For this challenge, deliver the following and attach them as evidence (repository links, PDFs, or videos as your coach specifies).

Product	Learning outcome	What you deliver
System design	Design & Realise	Self-contained design document: context, city requirements link-in, block diagram for multiple bays, circuit/wiring diagram, pin assignment table, locker state machine (diagram + description), timing parameters, software module overview for the shared firmware, per-bay data/control interface for full-stack, contribution to the city BOM, and test plan
Prototype realisation	Design & Realise	Working multi-bay prototype on your city tile (or documented bench stand-in), code integrated in the city’s shared firmware on GitLab `main`, README with build/upload steps, interface demo (live or simulated), and validation evidence showing coordinated behaviour on different bays

Suggested titles for Portflow

Design: City Parcel Locker — multi-bay hardware and firmware specification
Realisation: City Parcel Locker — multi-bay prototype and validation

System design — minimum contents

Your design document should let a peer rebuild and integrate the system without guessing:

Requirements. Per-bay rules for free / occupied, and door open/close; how this fits the city Requirements.
Architecture diagram. MCU, buttons, servos and LEDs per bay, OLED, optional presence, power, and the path to full-stack (protocol boundary).
State machine. States that cover idle, selected, door open, occupied, refuse, and optional pickup/override commands.
Timing table. Door open duration; when occupancy flips; presence timeout if used.
Pin map and wiring diagram. GPIO ↔ component for every bay; include resistor values for LEDs.
BOM. Parts list aligned with the city’s shared BOM (count servos and LEDs per bay).
Input handling. Debounce on buttons; presence filter if used.
Full-stack interface. Messages for status per bay, plus open/reserve/empty controls; example payloads; how to test with a stub or simulator.
Shared firmware. Where your modules live in the city codebase and which code conventions you follow.
Test plan. e.g. “select free A”, “A occupied”, “select B free”, “refuse occupied”, “override empty”, “interface lists both bays”.

Realisation — minimum evidence

Small test sketches (or a short test log) showing you verified parts separately: one door, LEDs, OLED, buttons, second bay — before integration.
Work on the city GitLab project: proven multi-bay behaviour merged (or ready to merge) into main as part of the shared firmware — not a dump of unfinished experiments into main.
Photo or diagram of the physical build on the tile (or bench stand-in with a clear path to the tile), with bays labelled.
Demo script (numbered steps) matching your video or live assessment, covering at least two bays and the data/control interface.
Proof you can progress without waiting on full-stack (simulation, Serial demo, or stub consumer).
Honest known limitations (e.g. one servo power rail, interface not yet wired to the Pi).

Quality indicators

When assessing this challenge as a whole, the following indicators are used. Use them as a self-check before you submit.

Problem fit

The bays you control and open / occupied rules are described in plain language.
Scope is explicit: this challenge delivers a multi-bay parcel locker on your city tile (at least two bays), integrated into shared firmware — not a single-door demo or a solo firmware fork.
The work respects the city Requirements (tile, shared firmware, BOM/wiring, full-stack interface, no waiting on classmates).

Analyse & Advise products

Research and advice reports meet the research and advisory report quality indicators.
The advice report references the research report and states one clear recommended architecture for coordinated bays, including how per-bay data and controls reach full-stack.
Component and approach choices are supported by datasheets or comparable evidence, not only opinion. Decisions cite resources.

Design

The design document is self-contained and includes a multi-bay state machine plus timing rules that match the intended firmware behaviour.
Pin map, wiring diagram, and BOM cover every controlled bay and match the realised prototype (or differences are documented with reason).
Fail-safe behaviour is designed explicitly (doors default closed, timeouts, clear free/occupied).
The data/control interface for full-stack is specified with example messages per bay.

Realisation

The prototype demonstrates bay selection, servo doors, occupancy LEDs, and OLED messages on at least two bays.
Behaviour lives in the city’s shared firmware on GitLab main (or is clearly opened as an integration MR), following city code conventions.
Firmware is readable: meaningful names, constants for thresholds/timings, no unexplained magic numbers.
Button input is debounced; door and occupancy changes are observable via Serial log or demo script.
The full-stack interface is demonstrable (live or with simulation/stubs) without depending on a finished back-end.
Validation evidence covers bay A, bay B, occupied refuse or pickup, and at least one edge case (e.g. double press, override empty).
Repository README explains how to build, flash, and run the multi-bay demo as part of the city project.

Professional practice

Learning Goal in Portflow uses the correct naming format and links to all product evidence.
End-of-sprint reflection connects results to your learning question and to embedded practice (timing, I/O, multi-bay coordination, city integration).
Documentation is in English Markdown and usable by other city students on their tiles.
You did not block on classmates: simulation, stubs, or a local demo kept you moving.

Focus points

Watch out for these common issues while you work:

Stopping at one bay. Two sprints mean a multi-bay result; one door alone is not enough for this challenge.
Ambiguous occupancy. Always define when free flips to occupied; test both deposit and (if implemented) pickup.
Everything in main firmware. Develop and test parts in small Arduino sketches first; only integrate working pieces into the shared city firmware.
Solo firmware forever. Test sketches are fine for learning; the assessed integration still joins the shared city firmware per the Requirements.
Waiting on full-stack. Define the interface early and demo with Serial/stubs; do not pause realisation until the Pi dashboard exists.
Blocking delay() everywhere. Long delay() calls miss button presses on other bays. Prefer millis()-based state machines or timers.
Two servos on weak power. Power servos appropriately; brown-outs look like “random” bugs.
Advice without analysis. Coaches will send back an advice report that invents new comparisons not present in research.
Design–code drift. Update the design document when you change pins, timings, bays, or interface messages during realisation.

Key points

Core task: select among bays → open/close doors and track free/occupied on your city tile.
Because this is Sprint 1-2, the delivered system is multi-bay (at least two lockers), not a single door.
Test small parts in separate Arduino sketches; integrate only what works into one shared firmware.
Expose per-bay status and controls for full-stack; keep a shared BOM and wiring diagram.
Deliver four products: research, advice, system design, and prototype realisation.
Work research → advice → design → realise; Sprint 1 emphasises research & advice (and proving one bay); Sprint 2 emphasises multi-bay design & realisation.
Carrier APIs / payments are out of scope; building the city back-end/front-end is out of scope for you.
Link everything to your Learning Goal in Portflow and reflect at the end of Sprint 1-2.