Future: build IR and Idriç/Edric by Example learning paths

[isomorphisms]

The eventual language documentation should include a short by-example path in the spirit of Rust by Example, Go by Example, tldr, bropages, and the koan style.

The core observation is simple: people often want one small example of a thing they can do, not a long chapter before they can act. A future IR by Example and Idriç / Edric by Example should therefore start with roughly a dozen tiny runnable examples and grow only as the implementations grow.

The companion koan-by-example branch contains a research note comparing Rust by Example and Go by Example, noting similar Python resources, and sketching a first twelve-example ladder. It also proposes pairing each working example with an optional koan: a blank, wrong value, or failing assertion for the learner to repair.

Research branch: https://github.com/isomorphisms/ir/tree/koan-by-example

Important constraint: examples must follow features the implementation can actually run. Do not copy Rust or Go's surface just because their tutorials cover it.

The first pass should emphasize concrete tasks such as hello world, values, bindings/equality, control flow, functions, data types, collections, conversion, errors, files/CLI, structured data or HTTP, and one characteristic runtime/concurrency example where supported.

Companion issues:

• Future: build IR and Idriç/Edric by Example learning paths Idric#36
• Future: build IR and Idriç/Edric by Example learning paths r-koans#4

[isomorphisms]

One useful supplement to the usual Rust-by-Example / Go-by-Example style would be a set of small complete programs that cross a real runtime/OS boundary, not just examples of language constructs. These can be revisited at several levels of detail: source language, IR, generated assembly, ABI/runtime calls, executable format, and the operating-system interface.

Candidate examples:

• Print X and exit. Start with the smallest complete program whose main prints one letter and terminates. Show exactly what survives into IR and machine code, and what startup/exit machinery exists around main.
• Use libc deliberately. Make a tiny program that calls one useful libc routine (even something as small as puts, or a later example such as qsort). Then inspect the generated assembly and ELF with readelf/objdump: show the call site, dynamic symbol/relocation if applicable, and where the libc dependency is recorded in the ELF file.
• Make the phone place/initiate a call. This is a good layered example because “call this number” can mean several different Android contracts: handing a number to the dialer, requesting a call through the framework, permissions/default-role restrictions, and finally the much lower telephony stack. The tutorial can stop at whatever boundary the implementation actually supports while naming the deeper layers.
• Flash the screen red for two seconds, then exit. A tiny graphics/lifecycle example: create one surface/window, fill it solid red, wait two seconds, tear it down, terminate. It gives us something concrete to trace from language → graphics/runtime boundary → framebuffer/GPU path without first building a UI framework.
• Read phone orientation from sensors. Read accelerometer (and, when appropriate, other orientation inputs), derive/display the phone’s current orientation in very large text, continuously update it, and provide one explicit Exit button. This is a compact example of sensor acquisition, event delivery, state update, rendering, and lifecycle cleanup.

The point is not that these all belong in the first twelve examples. They are useful because each is a complete thing a person might actually want a computer to do, and each can later be presented at one paragraph, one-page, and deep “follow it all the way down” levels.

[isomorphisms]

Follow-up idea: include a small device I/O by example ladder made of complete programs, not only language-feature snippets.

The useful pattern is: start with a real thing a person recognizes, show the layers underneath it, then choose one tiny executable slice at each layer.

Phone sensors

One complete program should simply enumerate every sensor/interface the device exposes and print a readable list. Keep two notions separate:

• Android-style sensor-service devices: accelerometer, gyroscope, magnetometer, gravity, linear acceleration, rotation vector, orientation-derived sensors, ambient light, proximity, pressure/barometer, relative humidity, ambient temperature, step counter/detector, significant motion, heart-rate/body sensors where present, etc.
• Other physical inputs that people reasonably call sensors but may live behind different APIs: cameras, microphones, GNSS/GPS, touchscreen, fingerprint/biometric hardware, USB devices, Bluetooth devices, Wi-Fi/radio state, battery/thermal sensors.

A second program can pick one sensor — say the accelerometer — and display x y z in very large type, updating live, with one Exit button. Then do the same for gyro, compass, light, proximity, etc. The tutorial should show where raw readings stop and derived concepts such as “portrait / landscape / face up” begin.

Nintendo Switch / motion controller example

Use the same shape for a Joy-Con or similar motion controller used for a tennis game. Pretend there is only a screen plus Bluetooth/USB input. The whole application can be:

1. connect to the controller;
2. read its input reports;
3. display stick/button state plus accelerometer and gyroscope coordinates in very large text;
4. Exit button.

That gives several layers that can each become a tiny lesson:

application → controller/input API → HID/report protocol → Bluetooth or USB transport → controller firmware → IMU hardware.

“Firmware” is useful terminology here: it is software living close to the hardware, normally stored on and executed by the embedded device itself. It is not the whole stack. The PC/phone driver and the tutorial application are ordinary host software even though they communicate with firmware in the controller.

Possible progressively lower examples:

• print one button state;
• print one stick coordinate;
• print one accelerometer axis;
• print the raw input-report bytes;
• decode those bytes into named fields;
• show a derived orientation;
• compare controller timestamps with host timestamps;
• connect, read one report, print it, disconnect, exit.

Radio / Wi-Fi layers

Do the same decomposition for a radio:

program → socket/network API → OS networking stack → Wi-Fi/Bluetooth driver → device firmware → radio/baseband → RF front end → antenna.

Then choose intentionally trivial observable programs at different levels: print the current interface/channel; print reported RSSI; print configured TX power if the platform exposes it; send one packet and exit; receive one packet and print its metadata; request a Bluetooth connection and show the resulting state.

The amusing “make the antenna play B-flat for three seconds” question is worth keeping because it forces the layers apart. B-flat is an audio-frequency concept — e.g. B♭4 is about 466.16 Hz — whereas a Wi-Fi antenna is radiating a carrier in the GHz range. A precise version would be something like “produce an RF transmission whose envelope or packet cadence is modulated at 466.16 Hz for three seconds.” Ordinary Wi-Fi hardware generally does not expose arbitrary waveform generation to normal applications; the driver/firmware/regulatory layer constrains channel, waveform and transmit behavior. An SDR or explicit hardware test mode is a different boundary. That distinction itself is a good tutorial example.

The recurring documentation rule should be: for a recognizable device behavior, draw the actual stack, then provide the smallest complete program we can honestly execute at one or more of those boundaries. Every example should terminate cleanly and GUI examples should have an obvious Exit button.

[isomorphisms]

Add an audio-output counterpart

The same tutorial idea should include one tiny complete audio program. The point is not music software; it is: there is a speaker on the phone, what is the smallest complete program that makes it produce a known waveform and tells us what path was used?

A good fixture would be a few synthesized notes from a public-domain Dvořák motif, generated directly rather than by shipping or replaying a recording. Keep it deliberately primitive: sine waves are enough.

Possible progression:

1. Open the platform's simplest audio-output device/stream.
2. Generate one fixed-frequency sine wave for perhaps 500 ms, then silence, then exit.
3. Generate three or four specified notes as a tiny melody.
4. While playing, show readable diagnostics on screen: requested sample rate, actual sample rate, channel count, sample format, frames written, underrun/error count if exposed, current note/frequency, and the API/device path selected.
5. Include an Exit button and make shutdown explicit: stop stream, release device, exit process.

Then peel the same example through layers, without pretending they are one thing:

program -> language/runtime call -> platform audio API -> mixer/audio service -> kernel/driver -> codec/DAC -> amplifier -> speaker diaphragm -> pressure wave

Each layer can have its own tiny by-example probe. For example:

• produce 440 Hz samples in memory but do not play them;
• write one buffer to an already-open PCM stream;
• inspect the audio device capabilities;
• demonstrate the exact native/FFI call crossing into the OS audio API;
• where practical, inspect what library or syscall boundary the executable actually reaches.

This is the audio analogue of the framebuffer/screen examples: a complete visible/audible effect first, followed by smaller probes that expose the machinery underneath it. Do not use a copyrighted recording as the fixture; synthesize the notes locally.

[isomorphisms]

Keep the low-level radio examples deliberately dumb

Bluetooth and Wi‑Fi are probably the wrong place for this particular by-example path. Pairing, discovery, authentication, protocol negotiation, coexistence, firmware, drivers, and platform policy quickly bury the primitive being taught. Treat those as SDK/platform-stack examples rather than pretending they are tiny NDK exercises.

A better low-level radio ladder is a deliberately simple bench link where the application meaning is literally one bit:

program -> GPIO/SPI/UART -> radio module -> RF -> radio module -> GPIO -> relay/LED

0 = off
1 = on

Use hardware and frequencies that are legal for the chosen module and only control hardware we own. A separate explanatory article can use a remote key fob as the familiar picture—button -> transmitter -> carrier/modulation -> coded message -> receiver -> decoder -> actuator—while explicitly stopping before code capture/replay or cloning.

Useful tiny programs/lessons:

1. receive only: initialize a simple receiver and print carrier/no carrier, RSSI, or one decoded bit in very large text; Exit button;
2. one-bit transmitter: on our own bench hardware, send 1 briefly to a paired receiver that lights an LED or energizes a harmless relay, then exit;
3. one-bit round trip: screen button -> one application bit -> remote LED -> acknowledgement -> print result;
4. layer peeling: show application call, OS/driver call, SPI/UART bytes, and the documented radio-module hardware interface;
5. key-fob anatomy article: distinguish carrier frequency, modulation, payload, and authorization, using our own toy fixed-code link rather than a real lock.

Citizens Band is useful mainly as a boundary example: acoustic/audio frequency and RF carrier frequency are different things. A voice may contain a 466 Hz component while the CB carrier is around 27 MHz; the audio modulates the carrier. For U.S. CB, use the service as designed rather than arbitrary RF generation. In particular, current FCC rules prohibit transmitting music or entertaining sound effects over CB, so the musical-tone exercise belongs in a simulator/dummy-load/SDR-lab path, not over the air.

The general pattern remains: take a physical capability, draw the real stack, then choose one tiny seam that can honestly become a complete diagnostic program with visible state and an Exit button.

[isomorphisms]

Side article: how does a song become a file?

Do not let this turn the by-example path into a codec course. After the raw-speaker example, one short article can explain the storage stack and then point to a good visual treatment.

The useful conceptual ladder is:

air pressure
-> microphone voltage
-> sampled numbers
-> PCM frames
-> optional compression/codec
-> file/container
-> decoder
-> PCM frames again
-> audio output
-> speaker

The first programming lesson should stop at raw PCM: e.g. 48,000 samples/second, one or two channels, a declared integer/float sample format, and a tiny generated waveform. That is enough to make the connection between numbers in memory and pressure waves from the speaker.

Then give only the vocabulary needed to understand ordinary music files:

• PCM: essentially the sample values themselves.
• WAV: commonly a simple container around PCM plus metadata.
• codec: rules for turning audio samples into another representation and back; examples include Vorbis, Opus, AAC, MP3.
• container: a file structure that can carry encoded streams plus metadata. Ogg and MP4 are containers, not themselves the audio encoding. An .ogg file often carries Vorbis or Opus; an .mp4/.m4a file often carries AAC, though containers can support more than one codec.
• lossless vs lossy: whether decoding reconstructs the original sample sequence exactly or an approximation designed to sound essentially the same while taking fewer bits.

There is no need here to implement Ogg, MP4, MP3, AAC, Vorbis, or Opus. A later example can simply call a platform decoder and show the boundary:

encoded file -> decoder API -> PCM buffer -> speaker

Print the interesting facts in large readable diagnostics: filename/container, codec if known, sample rate, channel count, duration, decoded PCM format, frames decoded/written, and any decode/output error; Exit button.

For a visual companion, Computerphile has two concise videos that fit this scope well:

• How Digital Audio Works — https://www.youtube.com/watch?v=1RIA9U5oXro
• Digital Audio Compression — https://www.youtube.com/watch?v=KGZ0een8vSE

The first is the better default link after the raw-speaker lesson; the second is the optional follow-up for why compressed music files are much smaller than naked PCM.