Railroad / Bridge Crossing

Picture a railroad or bridge crossing on your Learning Group's city tile. When a train or boat needs the road closed, the crossing must become safe: barriers lower, warning lights flash, and a sound alert warns road users. When the way is clear again, the crossing can be taken safely. That is embedded logic: an approach signal drives coordinated barriers, lights, and sound in real time.

In this challenge you design and build a safe crossing for your Learning Group city tile: detect an approaching train/boat stand-in, close the road with barrier(s), warn with lights and sound, then reopen when clear. Because this challenge spans two sprints, the delivered result is a multi-aspect system — not a single LED blink. 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 - Railroad / Bridge Crossing (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 (approach, barrier, warning light). Your delivered system must cover barrier + warning lights + sound plus an approach sensor, and keep the road closed until the crossing is clear.

Challenge

Your Learning Group city needs a safe railroad or bridge crossing on a city tile. When a train/boat stand-in approaches, barriers, warning lights, and sound must close the road safely; when clear, the crossing can be taken again. 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. Is this a railroad or bridge theme? Where is the approach detected? When do barriers lower vs rise? When do lights and sound run? Write clear rules, e.g. “Barrier down and lights flashing while approach is active; reopen only after clear + timeout.” Agree which tile template you use and how this challenge fits the city plan.
Research. Compare realistic ways to detect approach, drive barrier servo(s), and warn with lights and sound, plus how to sequence the phases safely. Include how you will expose crossing state and controls to the full-stack side (protocol options). Use datasheets and cite resources for decisions.
Advise. Recommend one architecture: microcontroller role in the shared city firmware, sensors, barriers, lights, sound, 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 closed / warning / open, thresholds, timing, 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 sensor, one servo barrier, lights, buzzer, then sequence) before you merge working pieces into the shared city firmware on GitLab main. Keep each test sketch tiny. Then demonstrate: approach → warn + close → clear → reopen. 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 crossing placed on that tile (or a clear bench stand-in while the tile is cut). Prefer a tile that supports a road crossed by rail/canal (e.g. infra-crossing or crossroads).
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-aspect crossing behaviour included.
A multi-aspect crossing that includes all of the following:
- At least one barrier driven by a servo (SG90 or similar); two barriers (one per road side) is preferred if time allows,
- Warning lights (LEDs flashing, or RGB / WS2812 as a clear warning pattern),
- A sound alert (buzzer) while the crossing is closed or warning,
- An approach sensor for a train/boat/vehicle stand-in (ultrasonic, IR, PIR, or button as a clear stand-in).
Firmware that sequences the aspects safely. Example pattern:
- Idle: barrier raised (or documented open), lights off/steady safe, sound off,
- Approach detected → warning lights + sound, then barrier lowers,
- While closed: road blocked; after clear (sensor free) + timeout → barrier rises, warnings stop.
A documented phase sequence (approach → warn → close → clear → open). Keep it simple and explain your choice.
Filtering or debouncing on the approach sensor and timeouts so the crossing cannot stay closed forever after a false trigger, or reopen while approach is still active.
A documented data and control interface for full-stack developers: approach status, barrier position/state, warning active, plus commands that can request close/open or force a safe state (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 second barrier on the opposite road side with the same close/open rules.
Serial debug output showing approach reading and phase state.
A simple track/canal model (tape, cardboard) so sensor aim is obvious in demos.
A second approach sensor (train from both directions, or boat + road vehicle stand-in).
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 railway signalling standards, interlocking with distant stations, or certified barriers.
Pedestrian gates as a full separate mode (a simple shared barrier is enough).
Computer vision / ML train detection.
Production PCB fabrication.
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 street-legal infrastructure:

Default to closed / warning when the approach sensor is unsure during an active sequence; never leave the barrier up while you claim a train/boat is present.
Predictable rules. Document exactly when each aspect changes relative to detection and timeouts.
Clear demo script. Anyone in your Learning Group can show at least: clear → open/idle; approach → lights + sound + barrier down; clear → reopen after timeout.
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 (infra-crossing or similar works well) and sketch barrier, lights, sound, and sensor placement.
Agree on phase rules. When does warning start, when does the barrier move, and when may the road reopen? Write rules in plain language.
Inventory hardware. List what your studio kit provides (ESP32, servo, LEDs, buzzer, breadboard, approach sensor). 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. servo sweep, LED blink pattern, buzzer tone, approach sensor, then the full sequence). 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 (crossing state messages and a force-close example). 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 approach sensor, barrier actuator, and warning outputs best fit a safe crossing tile given timing, false triggers, 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 sensor + one actuator in sketches, then lights and sound, then full sequence; 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-aspect sequence) and prove one subsystem (e.g. approach sensor or barrier) in small sketches. In the second sprint you focus on design and realisation of the full multi-aspect system: remaining outputs, sequencing, shared-firmware integration, and the full-stack interface.

Sprint	Focus	Outcome
1	Research & advise (+ first subsystem in sketches)	Research report; advisory report; tile and phases chosen; close/open rules; hardware choice; draft data/control interface; one subsystem proven in a small test sketch
2	Design & realisation (multi-aspect)	Wiring diagram + pin map + crossing state diagram; shared BOM updated; barrier + lights + sound + sensor coordinated in shared firmware on city GitLab `main`; demo of full sequence (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 (barrier); LEDs / RGB / optional WS2812 warning strip; buzzer
Sensors	Ultrasonic (HC-SR04), IR, PIR, or button as approach stand-in; optional laser KY-008 break-beam
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 approach detection and coordinated barrier / warning / sound control; comparison with criteria; recommendation for design	Research product
Advice	Decision document: chosen MCU role in shared firmware, sensor and multi-aspect outputs, phase rules, full-stack data/control interface, and implementation order (sensor → barrier → lights/sound → sequence)	Advisory report

Suggested titles for Portflow

Research: Approach sensing for safe railroad / bridge crossing
Advice: Multi-aspect crossing barrier and warning 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 multi-aspect crossing, circuit/wiring diagram, pin assignment table, crossing state machine (diagram + description), timing parameters, software module overview for the shared firmware, data/control interface for full-stack, contribution to the city BOM, and test plan
Prototype realisation	Design & Realise	Working multi-aspect 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 approach → close → reopen behaviour

Suggested titles for Portflow

Design: Railroad / Bridge Crossing — multi-aspect hardware and firmware specification
Realisation: Railroad / Bridge Crossing — multi-aspect prototype and validation

System design — minimum contents

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

Requirements. Rules for approach / clear, and phase order for barrier, lights, and sound; how this fits the city Requirements.
Architecture diagram. MCU, approach sensor, barrier servo(s), lights, buzzer, power, and the path to full-stack (protocol boundary).
State machine. States that cover idle/open, warning, closed, clearing, and optional override commands — never reopen while approach is still active without a documented reason.
Timing table. Warning-before-close delay; minimum closed time; clear timeout before reopen.
Pin map and wiring diagram. GPIO ↔ component for every aspect; include resistor values for LEDs.
BOM. Parts list aligned with the city’s shared BOM.
Sensor handling. Threshold, debounce/filter, and timeout logic for approach.
Full-stack interface. Messages for approach status and crossing phase, plus controls/overrides; 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. “idle open”, “approach → warn + close”, “still approach → stays closed”, “clear → reopen”, “override forces closed”.

Realisation — minimum evidence

Small test sketches (or a short test log) showing you verified parts separately: approach sensor, barrier, lights, buzzer, then sequence — before integration.
Work on the city GitLab project: proven multi-aspect 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 aspects labelled.
Demo script (numbered steps) matching your video or live assessment, covering barrier + lights + sound + sensor 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. servo jitter, 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 crossing phases and approach / clear rules are described in plain language (when barrier, lights, and sound run).
Scope is explicit: this challenge delivers a multi-aspect crossing on your city tile (barrier + lights + sound + sensor), integrated into shared firmware — not a single-actuator 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 aspects, including how crossing 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-aspect state machine plus timing rules that match the intended firmware behaviour.
Pin map, wiring diagram, and BOM cover barrier, lights, sound, and sensor and match the realised prototype (or differences are documented with reason).
Fail-safe behaviour is designed explicitly (safe closed/warning when unsure during active approach, timeouts, no reopen-while-busy).
The data/control interface for full-stack is specified with example messages for crossing state.

Realisation

The prototype demonstrates approach detection, barrier motion, warning lights, and sound in a safe sequence.
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.
Sensor input is filtered or debounced; phase 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 idle, approach/close, clear/reopen, and at least one edge case (e.g. brief false trigger, override).
Repository README explains how to build, flash, and run the multi-aspect 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, safety, multi-aspect sequencing, 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 aspect. Two sprints mean barrier + lights + sound + sensor; a lone servo demo is not enough.
Reopening too early. Always define clear + timeout; test that case on purpose.
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 approach changes. Prefer millis()-based state machines or timers.
Servo power. Do not starve the MCU; power the servo appropriately and document it.
No clear idle state. Define what “safe to cross” looks like when no approach is present.
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, thresholds, timings, or interface messages during realisation.

Key points

Core task: detect approach → warn and close the road safely → reopen when clear on your city tile.
Because this is Sprint 1-2, the delivered system is multi-aspect (barrier + lights + sound + sensor), not a single output.
Test small parts in separate Arduino sketches; integrate only what works into one shared firmware.
Expose crossing data 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 subsystem); Sprint 2 emphasises multi-aspect design & realisation.
Certified railway systems and city-wide networks beyond your tile 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.