Pico

Building your first Pico.

Welcome to Pico, the reference course of the Open Engineering Academy. This course teaches how to design and build your first Pico — a small, declarative, composable engineering artifact — and doubles as the canonical example for how every academy course website is structured.

Where this course fits

Pico is the academy’s behaviour layer. The three-layer story is:

Crossplane composes, Sandcastle constructs, Picos behave.

This course teaches what a Pico does at runtime — how a hello-world-pico receives events, evaluates rules, and produces actions. Its sibling courses teach the other two layers:

• Crossplane course — declares and composes what should exist on a control plane.
• Sandcastle course — the bounded engineering environment inside which artifacts like Picos are safely built.

Pico is the foundation for the other two: complete this course first so you know what a durable Pico artifact looks like before you compose it with Crossplane or construct it inside a Sandcastle.

What you will learn

By the end of the course you will be able to:

• Explain what a Pico is and how it fits into Open Engineering.
• Author Rules, a Parser, and a Composer for a minimal Pico.
• Produce a working hello-world-pico and describe it with metadata.
• Distinguish a Pico’s Mind (whether/why it should act) from its Hands (how an action is executed), and explain why Hands stay provider-neutral. See Part 3 · Hands.
• Place a Pico’s Nervous System after Hands in the Pico progression and distinguish Brain/Mind, Hands, Voice (what a Pico communicates outward), and the transport-neutral fabric those messages travel through. The course defines provider-neutral message semantics — envelope, observation, event, command, delegation, result, presence, discovery, and topic/capability authorization — before naming MQTT or EMQX as candidate transport implementations. See Constructive realization · Nervous system as a governed extension.

See the course descriptor in metadata.yaml for the machine-readable summary (id, level, duration, prerequisites, teaches, produces).

How this course is structured

The course is organized into parts, each part into lessons, and each lesson into a consistent set of pages:

courses/pico/
  _quarto.yml          # this course website
  index.qmd            # you are here
  metadata.yaml        # machine-readable course descriptor
  glossary.qmd         # course glossary
  part-1/              # section
    index.qmd
    01-introduction/   # lesson
      index.qmd
      exercise.qmd
      lab.qmd
      summary.qmd
      quiz.qmd
      assets/
  part-2/
  part-3/
  labs/                # course-scoped labs
  assets/              # course-scoped assets

Start here

• Part 1 — Foundations
• Part 2 — Building
• Part 3 — Extending
• Labs and the shared Hello Pico lab.
• Constructive realization — how Definition, Element, Realization, Constraint, and Validation map onto the Rules → Parser → Composer → Pico pipeline.
• Hello Pico as a constructive exemplar — the first worked example, pointing each of those terms at concrete Hello Pico material.
• Glossary
• Open Engineering Language Server (OELS) — optional learner guide for installing OELS locally and reading its diagnostics on OE-shaped Pico YAML (see the reference Pico at courses/make-the-lamp-nod/picos/pixstars-head-pitch.yaml).

Reference course notice

This course is the reference implementation for all other academy course websites. When authoring a new course under courses/<name>/, mirror the files, navigation, and lesson structure used here.