My Blog

Balancing a Furuta Pendulum: From Plant Modelling to Cascade Control

GuanHua Yu — Thu, 20 Aug 2026 00:00:00 GMT

Balancing a Furuta Pendulum: From Plant Modelling to Cascade Control

The inverted pendulum is one of those control problems that looks simple in a diagram and becomes much more interesting as soon as the model is connected to a real actuator.

In this project, I worked with a Furuta-type rotary inverted pendulum. A motor drives a horizontal arm through a gearbox, while a pendulum is attached at the end of the arm. The primary objective is to keep the pendulum upright:

$$ \alpha = 0 $$

but doing that alone is not enough. The rotary arm angle $\theta$ also has to remain controlled.

That second requirement became the most important lesson of the project.

A single-loop controller could recover the pendulum angle after a disturbance, yet the arm itself slowly drifted away. The system only behaved the way I actually wanted after I introduced a cascade controller: a fast inner loop for $\alpha$ and a slower outer loop for $\theta$.

The Furuta pendulum couples a rotary arm and an inverted pendulum through one motor-driven mechanical system.

This project gave me a practical way to connect several control concepts that can otherwise feel separate:

mechanical modelling
    -> transfer functions
    -> root locus
    -> PID design
    -> nonlinear simulation
    -> cascade control
    -> disturbance rejection

Start with the Mechanical Model

Before designing a controller, I first had to determine the effective rotational inertia seen at the arm axis.

The motor, tachometer, gears, encoder, potentiometer, and arm all contribute inertia, but the gear train reflects each inertia through the square of the gear ratio.

For a generic gear pair,

$$ J_{\text{reflected}}

\left( \frac{N_{\text{output}}}{N_{\text{input}}} \right)^2 J $$

After referring the drivetrain components to the rotary axis and adding the arm inertia,

$$ J_{\text{arm}} = \frac{mr^2}{3} $$

the total effective inertia in my model was approximately:

$$ J \approx 0.00608\ \text{kg}\cdot\text{m}^2 $$

This part of the project reminded me that controller design depends directly on mechanical assumptions.

A root locus can look perfect for the wrong plant.

So I now think of modelling error as something that should be treated with the same seriousness as tuning error.

From Motor Voltage to Pendulum Motion

The plant contains both the pendulum mechanics and the motor electrical dynamics.

The motor torque depends on the applied voltage, armature resistance and inductance, motor constants, gearbox ratio, and back EMF.

The resulting model gave me two useful transfer functions:

motor voltage Va
    -> pendulum angle alpha
    -> rotary arm angle theta

In MATLAB, I also rebuilt the transfer functions using series, feedback, and minreal to check the algebraic derivation.

That verification step was useful because complicated symbolic expressions are easy to get wrong.

The normalized pendulum-angle plant was approximately:

$$ \frac{\alpha(s)}{V_a(s)}

\frac{3.801\times10^5s} {s^4+1.444\times10^4s^3+2.123\times10^5s^2-1.002\times10^6s-9.286\times10^6} $$

The important part was not memorising the coefficients.

It was establishing one consistent plant model that could be used for:

root-locus design;
MATLAB verification;
Simulink simulation;
later cascade-control analysis.

Lesson 1 - Translate Time-Domain Requirements into Pole Regions

The inner controller was designed to regulate the pendulum angle $\alpha$.

The required transient response was:

$$ T_p \leq 0.2\ \text{s} $$

and

$$ %OS \leq 20% $$

For a dominant second-order approximation,

$$ T_p = \frac{\pi}{\omega_d} $$

so:

$$ \omega_d \geq 5\pi $$

The overshoot requirement gives approximately:

$$ \zeta \geq 0.456 $$

Those two equations convert a time-domain specification into an allowed region of the $s$-plane.

That was the part of root locus that became much more meaningful to me during this project.

Instead of asking:

"Where should I put the poles?"

I could ask:

"Which pole locations correspond to the response I actually want?"

The root-locus design region was defined by the peak-time and damping-ratio requirements.

Lesson 2 - PID Design Is Easier to Understand as Pole-Zero Shaping

The inner loop used a PID compensator:

$$ PID_\alpha(s)

K_{P,\alpha} + K_{D,\alpha}s + \frac{K_{I,\alpha}}{s} $$

I selected two real zeros and an integrator.

The final compensator was:

$$ PID_\alpha(s)

2.4\frac{(s+25)(s+8.5)}{s} $$

which gives:

$$ K_{D,\alpha}=2.4 $$

$$ K_{P,\alpha}=80.4 $$

$$ K_{I,\alpha}=510 $$

The inner loop uses the pendulum-angle error to generate the motor-voltage command.

I found it more useful to think of this controller as a pole-zero shaping device than as three independent gains.

The integrator changes the low-frequency structure.

The two zeros reshape the root locus.

The overall gain then selects the closed-loop pole locations.

That viewpoint made the tuning process much less arbitrary.

The Linear Controller Met the Original Specification

The closed-loop step response gave:

$$ T_p = 0.0619\ \text{s} $$

and

$$ %OS = 14.1389% $$

Both values satisfy the original requirements.

The designed inner PID loop meets the peak-time and overshoot requirements in the linear model.

At this stage, it would be tempting to say that the controller design was finished.

The nonlinear simulation showed why that conclusion would have been premature.

Lesson 3 - Stabilising the Pendulum Is Not the Same as Controlling the System

I implemented the PID controller in the nonlinear Simulink plant and applied a short voltage disturbance:

$$ V_d(t)=u(t-1)-u(t-1.025) $$

The pendulum angle behaved well.

After the disturbance, $\alpha$ returned close to zero.

But the arm angle $\theta$ did not.

The inner PID loop recovers the pendulum angle, but the rotary arm position continues to drift because theta is not directly regulated.

This result was one of the most useful parts of the project.

The controller was doing exactly what I had asked it to do.

It was minimising:

$$ e_\alpha(t)=\alpha_{\text{ref}}(t)-\alpha(t) $$

with:

$$ \alpha_{\text{ref}}=0 $$

There was no term in that loop asking the arm to return to its original position.

So when the arm moved to recover the pendulum, nothing forced $\theta$ back to zero.

This is a very general control lesson:

A controller cannot regulate a variable that never appears in its feedback objective.

The problem was not that the inner PID was badly tuned.

The problem was that the control architecture was incomplete.

Lesson 4 - Cascade Control Solves a Structural Problem

The solution was to add a second loop.

The inner loop remains responsible for keeping the pendulum upright.

The outer loop regulates the rotary arm angle.

flowchart LR
    R["Theta Reference"] --> O["Outer PD"]
    O --> A["Alpha Reference"]
    A --> I["Inner PID"]
    I --> P["Pendulum Plant"]
    P --> AL["Alpha"]
    AL --> ARM["Arm Dynamics"]
    ARM --> TH["Theta"]

The important requirement is that the inner loop should be faster than the outer loop.

The outer controller assumes that when it requests a small change in $\alpha_{\text{ref}}$, the inner controller can realise that request quickly enough.

The outer theta loop generates the reference for the faster inner alpha loop.

This gave me a more practical understanding of hierarchical control.

The two loops do not have equal responsibilities.

The inner loop handles the fast unstable pendulum dynamics.

The outer loop handles the slower arm-position objective.

Lesson 5 - The Outer Controller Should Respect the Inner-Loop Dynamics

For the outer loop, I used a PD compensator with a first-order derivative filter.

The tuned controller was approximately:

$$ PD_\theta(s) \approx -0.01735 \frac{1+3.1s}{1+0.15s} $$

An equivalent Simulink PID-block representation was:

$$ P_\theta=-0.01735 $$

$$ D_\theta=-0.05074 $$

$$ N_\theta=6.57 $$

The selected zero and pole were approximately:

$$ z=-0.325 $$

$$ p=-6.57 $$

The compensated outer-loop poles remain in the left-half plane, with the slowest pole dominating the arm response.

The dominant closed-loop pole was approximately:

$$ s_1=-0.378 $$

while the remaining poles were further into the left-half plane.

That is exactly what I wanted from the cascade architecture: a visibly slower outer loop wrapped around a faster inner loop.

Lesson 6 - Stability Margins Are More Informative Than a Stable Pole Plot Alone

I also checked the compensated outer loop in the frequency domain.

The resulting margins were approximately:

$$ GM = 6.8\ \text{dB} $$

and

$$ PM = 60^\circ $$

The outer-loop controller retains useful gain and phase margins after compensation.

The poles tell me whether the nominal model is stable.

The gain and phase margins give another view of how much uncertainty or additional phase lag the loop can tolerate before losing stability.

That distinction became more important to me once the controller moved from a transfer-function diagram into a nonlinear simulation.

Lesson 7 - Non-Minimum-Phase Behaviour Can Look Wrong Even When It Is Correct

The outer-loop step response initially moved in the opposite direction from the commanded arm motion.

Then it reversed and moved toward the reference.

The cascade controller keeps both angles bounded and removes the long-term arm drift seen with the single-loop controller.

My first instinct when seeing an inverse response like this is to suspect a sign error.

In this case, the behaviour was expected from the non-minimum-phase nature of the inverted-pendulum system.

This is an important debugging habit:

An unintuitive transient is not automatically an implementation bug.

Before changing gains or signs, check whether the plant itself contains zeros or coupled dynamics that predict the behaviour.

Lesson 8 - A Good Inner Loop Makes the Outer Loop Possible

In the nonlinear cascade simulation, both variables remained bounded.

The pendulum angle $\alpha$ moved during the transient and then returned close to zero.

The rotary arm angle $\theta$ also returned to the intended value instead of continuing to drift.

This is what the single-loop controller could not achieve.

Conceptually:

Inner loop:
keep alpha near zero

Outer loop:
choose alpha_ref so theta goes where we want

That is the key idea behind the architecture.

The outer loop does not directly command motor voltage.

It requests a pendulum-angle behaviour from the inner loop.

That separation of objectives is what makes the cascade structure work.

Lesson 9 - Test More Than One Reference and More Than One Disturbance

I tested the nonlinear cascade controller with several cases:

10 degree theta reference, no disturbance
20 degree theta reference, no disturbance
20 degree theta reference, 0.5 V disturbance
20 degree theta reference, 2 V disturbance

The same cascade controller was tested with different reference magnitudes and disturbance levels.

The 10-degree and 20-degree cases both showed the expected initial inverse response before $\theta$ moved toward the command.

For the disturbance tests, the voltage disturbance was applied at:

$$ t=1.25\ \text{s} $$

The 0.5 V case produced a relatively small additional transient.

The 2 V case produced a more aggressive response, especially in $\alpha$, but both angles remained bounded and recovered.

This is a much stronger validation than showing only one clean nominal step response.

A controller that performs well on one operating point may still be fragile.

Even simple variation in reference magnitude and disturbance size can reveal a lot.

What I Would Change in a Second Version

1. Separate model validation from controller tuning

I would first validate the plant model against experimental data before spending too much time refining the compensator.

A precise controller for an inaccurate plant is not necessarily useful.

2. Add actuator saturation explicitly

The linear design assumes the requested motor voltage is available.

A practical implementation should include:

voltage saturation
rate limits
anti-windup

especially because the inner loop contains integral action.

3. Quantify the cascade bandwidth separation

Instead of only reasoning qualitatively that the inner loop is faster, I would compare closed-loop bandwidths directly.

A practical target could be expressed as:

$$ \omega_{\text{BW,inner}} \gg \omega_{\text{BW,outer}} $$

4. Compare linear and nonlinear responses systematically

The nonlinear model exposed behaviour that the simple linear step response did not.

I would automate comparison across:

linear model
nonlinear model
different disturbances
different references
parameter perturbations

5. Move toward state-space control

For a coupled system such as the Furuta pendulum, a state-space design would be a natural next step.

It would allow the arm and pendulum states to be handled inside one multivariable framework instead of coordinating two SISO loops.

The cascade design is very useful for understanding the system, but it also makes the coupling visible enough to motivate more advanced control methods.

Final Thoughts

The most important lesson from this project was not how to tune a PID controller.

It was learning that control performance depends on choosing the correct architecture before choosing the gains.

The inner PID controller was successful by its own specification:

it met the peak-time requirement;
it met the overshoot requirement;
it recovered the pendulum after a disturbance.

And yet the complete system still had an undesirable behaviour: the rotary arm drifted.

The cascade controller solved that because it added the missing control objective.

That changed the way I think about feedback design.

I now ask these questions before tuning:

Which variables actually need regulation?
Which dynamics are fast and which are slow?
What should each loop be responsible for?
Does every important variable appear somewhere in the feedback architecture?
Is an unexpected transient caused by the controller, or by the plant itself?

The project started as a PID and root-locus exercise.

For me, it ended as a lesson in system-level control architecture:

A well-tuned controller can still solve the wrong problem. Good control design starts by deciding what the complete system must regulate.

Building a Real-Time Embedded DAQ System: Lessons from Firmware, Sensors, and Integration

GuanHua Yu — Thu, 20 Aug 2026 00:00:00 GMT

Building a Real-Time Embedded DAQ System: Lessons from Firmware, Sensors, and Integration

Some embedded projects look simple when reduced to a block diagram: sample a few signals, process them on a microcontroller, and send the values to a PC. In practice, the difficult part is rarely a single peripheral or a single function. The real challenge is making hardware, firmware, timing, communication, and user-facing software behave like one system.

I learned this while working on an industrial-style multi-channel data acquisition system. The final prototype combined voltage acquisition, acceleration and temperature sensing, configurable alarms, non-volatile settings, a local LCD interface, and a Qt-based desktop application for visualization and logging.

My main responsibility was the firmware side of the project, especially sensor integration, alarm control, EEPROM configuration, and communication with the GUI. Looking back, the most valuable part of the project was not learning another I2C register map or writing another UART interrupt routine. It was learning how to reason about the interfaces between modules.

An early proof-of-concept prototype used to bring the firmware, display, sensors, and communication path together.

System at a Glance

The system was organized around eight logical channels:

Channels	Signal	Main role
CH1-CH4	Voltage	Multi-channel external voltage acquisition
CH5-CH7	Acceleration X/Y/Z	Motion sensing through a 3-axis accelerometer
CH8	Temperature	Board/environment temperature monitoring

Around these channels, the firmware also had to manage alarm thresholds, alarm modes, display updates, persistent configuration, and serial communication with the PC application.

A simplified view of the architecture is:

flowchart LR
    V[Voltage Inputs CH1-CH4] --> AFE[Analog Front End]
    AFE --> ADC[Multi-Channel ADC]

    ACC[LIS3DH Accelerometer] --> MCU[ATmega328P Firmware]
    TMP[LM335 Temperature Sensor] --> MCU
    ADC --> MCU

    MCU --> LCD[Local LCD]
    MCU --> LED[Alarm LEDs]
    MCU --> EEPROM[EEPROM Configuration]
    MCU <--> UART[UART Protocol]
    UART <--> GUI[Qt GUI / Logger]

This diagram looks clean. The implementation was not.

The system only became reliable after the boundaries between these blocks were treated as engineering contracts rather than informal assumptions.

Lesson 1 - Requirements Should Drive the Component Choice

One of the largest changes happened around the ADC.

The early plan used a lower-cost ADC because it looked sufficient during initial planning. Once the full sampling requirements were considered, it became clear that the device could not satisfy the required combination of resolution, sampling rate, and simultaneous multi-channel acquisition.

The design was therefore changed to an ADS8584S, which supports simultaneous four-channel conversion and a much higher sampling rate.

That change solved one problem but immediately created several new ones:

more complicated timing control;
parallel or higher-throughput data handling;
multi-channel synchronization;
larger buffering requirements;
additional firmware states;
more integration work with the analog front end.

This was an important lesson for me: a cheaper or simpler part is not actually simpler if it pushes complexity into the rest of the system.

A component decision should not be evaluated only by unit price or headline specifications. I now try to ask four questions much earlier:

Does it satisfy the worst-case requirement rather than the nominal case?
What new firmware states does it introduce?
What timing assumptions does it create?
How difficult will it be to verify during integration?

In embedded design, the cost of changing a component late is often much larger than the cost difference between the components themselves.

Lesson 2 - The Firmware-to-GUI Interface Is an API

My firmware had to continuously exchange configuration and measurement data with the desktop application. At first, it is tempting to think of UART as simply "printing values."

That approach breaks very quickly once both sides become non-trivial.

The GUI needed more than a number. For each channel, it needed context such as current value, alarm state, alarm mode, thresholds, and sensor metadata. The firmware also needed to receive commands for connection state, configuration updates, and logging control.

I therefore treated the serial format as an explicit protocol.

The communication format defined a fixed layout so the GUI could interpret each channel deterministically.

A simplified conceptual frame looked like this:

DAT | input-range | CH1 | CH2 | CH3 | CH4 | CH5 | CH6 | CH7 | CH8

The important part was not the delimiter itself. The important part was that both sides agreed on the meaning and order of every field.

The receive path also used defined command tags rather than arbitrary free-form text. Commands represented events such as:

<STA>    GUI connected
<END>    GUI disconnected
CFG...   configuration update
LOGS     start logging state
LOGE     end logging state

This separation made debugging much easier. When something failed, I could ask a precise question:

Is the sensor value wrong, is the packet wrong, or is the GUI parser wrong?

Without a protocol contract, all three problems can look identical from the user interface.

The UART receive path parses complete messages and converts them into system-level events.

:::tip[What I would do differently] If I rebuilt this system, I would define the protocol document before writing either the firmware parser or the GUI parser. I would also include an explicit protocol version and checksum from the first revision rather than treating them as later improvements. :::

Lesson 3 - Sensor Integration Is About Data Meaning, Not Just I2C

The 3-axis accelerometer was one of the more useful examples of why "the communication works" does not mean "the sensor works."

The accelerometer used I2C. At the bus level, the task was straightforward:

configure the device;
select the output register;
read six consecutive bytes;
combine low and high bytes;
convert the result into signed axis values.

But several details mattered:

the output data rate;
the selected measurement range;
high-resolution mode;
byte ordering;
signed conversion;
update timing;
how the values were mapped to application channels.

A register transaction can be electrically correct and still produce useless application data.

For this project, the accelerometer values became CH5, CH6, and CH7. That meant the sensor driver also had to fit the timing model and packet model used by the rest of the system.

This changed how I think about drivers. A useful embedded driver is not only:

read_register();
write_register();

It should expose meaningful data at a predictable time.

For example, the application layer should be able to think in terms of:

accel_update();
get_accel_x();
get_accel_y();
get_accel_z();

rather than repeatedly reconstructing low-level transactions.

That boundary becomes increasingly important as a project grows.

Lesson 4 - "Real-Time" Often Starts with Scheduling Discipline

This system did not need a full RTOS to benefit from real-time thinking.

Different tasks naturally operated at different rates:

alarm checking needed relatively frequent updates;
environmental and motion sensors could update more slowly;
serial command parsing had to remain responsive;
display and GUI transmission had their own update cadence.

A simplified main-loop structure looked conceptually like this:

while (1) {
    parse_uart_commands();

    if (elapsed_ms(last_alarm_check) >= 10) {
        update_alarms();
        last_alarm_check = now_ms();
    }

    if (elapsed_ms(last_sensor_update) >= 100) {
        update_temperature();
        update_accelerometer();
        last_sensor_update = now_ms();
    }

    if (gui_connected) {
        transmit_latest_frame();
    }
}

The exact implementation details are project-specific, but the principle is general:

Do not let every module run whenever it wants.

Even a simple cooperative loop becomes much easier to reason about when each task has an expected period and bounded responsibility.

This also made instrumentation easier. We could use a logic analyzer and serial output to check whether a sensor update or transaction was completing within the expected time.

The lesson carried into my later work with RTOS-based and DMA-based systems: an RTOS does not automatically make a system real-time. Clear timing ownership does.

Lesson 5 - Configuration Persistence Changes the Product Experience

The alarm subsystem supported configurable thresholds and modes. Those settings were controlled from the GUI and stored in EEPROM.

This sounds like a small feature, but it changed the character of the device.

Without persistent configuration:

power on;
connect GUI;
re-enter settings;
start using the system.

With EEPROM-backed configuration:

power on;
restore the previous known state;
validate it;
operate immediately.

I used a validity marker so startup code could distinguish between valid saved data and uninitialized EEPROM. If the configuration was invalid, the firmware fell back to defaults.

Conceptually:

if (eeprom_signature == CONFIG_VALID) {
    load_config_from_eeprom();
} else {
    load_default_config();
}

That pattern is simple, but it introduced an important product-level concept: startup state is part of the interface.

Embedded systems are often judged by what happens at the boundaries - boot, disconnect, reconnect, reset, sensor failure - rather than only by their steady-state behavior.

Lesson 6 - Hardware and Software Must Be Integrated Early

One of the biggest sources of wasted time in team projects is waiting until each subsystem is "finished" before integration.

Our system had several independently developed parts:

analog and digital hardware;
firmware;
the PC GUI;
sensor modules;
display and alarm logic.

The PCB and the desktop interface were being developed in parallel with the firmware.

The PCB stage forced firmware assumptions to become concrete pin, voltage, interface, and timing decisions.

The GUI also made integration issues visible very quickly.

The desktop interface provided real-time visualization, configuration, and data logging for the embedded system.

When the GUI displayed a wrong value, the root cause could be almost anywhere:

Sensor
  -> electrical interface
  -> driver
  -> conversion
  -> channel mapping
  -> packet formatting
  -> serial transport
  -> parser
  -> plot

That debugging chain is why I now prefer vertical integration.

Instead of finishing every driver first, I would rather make one channel work end-to-end:

one sensor -> one firmware path -> one packet field -> one GUI display

Then scale the pattern to the remaining channels.

This produces a working reference path early and reduces the number of unknowns during debugging.

:::important[The integration lesson] A module is not finished when its unit test passes. It is finished when the next module can consume its output reliably. :::

What I Would Improve in a Second Version

If I were to redesign the system today, I would keep the same modular direction but make several changes earlier:

1. Define protocol versioning from day one

A simple version field would make firmware and GUI compatibility much easier to manage.

2. Separate acquisition from presentation more aggressively

Sampling, alarm evaluation, packet generation, and LCD updates should consume a shared data model instead of depending on each other directly.

3. Add structured error reporting

Instead of only transmitting measurement frames, I would include explicit status flags for sensor faults, stale data, buffer overflow, configuration errors, and communication timeouts.

4. Build an automated protocol test harness

A Python script could emulate the GUI, replay command sequences, and validate outgoing frames without requiring the full desktop application.

5. Schedule integration checkpoints

A team integration session every week would have exposed interface mismatches earlier and reduced rework near the end of the project.

Final Thoughts

This project changed my understanding of embedded systems.

Before building it, I tended to think about firmware mainly in terms of peripherals: ADC, I2C, UART, EEPROM, GPIO.

After building it, I started thinking more in terms of:

interfaces;
timing;
state;
data ownership;
failure boundaries;
integration contracts.

Those concepts are less visible than a schematic or a code listing, but they are what allow a prototype to become a system.

The most useful lesson I took away is simple:

Good embedded design is not about making every module individually clever. It is about making the boundaries between modules boring, predictable, and easy to debug.

That is a principle I have kept using in later embedded, FPGA, and edge-computing projects.

Designing a Multiplierless ADFT on FPGA: Pipelining, Fixed-Point Arithmetic, and Spectrum Sensing

GuanHua Yu — Thu, 20 Aug 2026 00:00:00 GMT

Designing a Multiplierless ADFT on FPGA: Pipelining, Fixed-Point Arithmetic, and Spectrum Sensing

One of the most useful FPGA exercises I worked through was implementing a small spectrum-sensing pipeline based on an 8-point Approximate Discrete Fourier Transform (ADFT).

At the algorithm level, the idea is attractive: instead of implementing a conventional DFT with a large number of complex multiplications, the approximate transform replaces its coefficients with structures that can be realised through addition, subtraction, and binary shifts.

That sounds like a straightforward hardware optimisation.

In practice, the more interesting part was everything that came after the equation:

deciding how to represent the arithmetic in fixed point;
mapping the transform into a parallel datapath;
balancing pipeline delays;
verifying hardware against MATLAB;
measuring the real critical path after synthesis and routing;
integrating ROM, SIPO registers, power estimation, and display logic into a standalone FPGA system.

This project gave me a much clearer view of the difference between an algorithm that is hardware-friendly and a hardware architecture that is actually well designed.

The transform can be expressed as a butterfly-style network in which constant multiplications are replaced by add/subtract and shift operations.

Why Approximate the DFT at All?

For an $N$-point DFT,

$$ X[k] = \sum_{n=0}^{N-1} x[n]e^{-j2\pi kn/N} $$

the straightforward implementation contains many complex multiplications.

For only eight points, this is not a huge problem on a modern FPGA. But the exercise becomes interesting when the design goal changes from:

"Can the FPGA calculate this?"

to:

"Can the transform be expressed using cheaper hardware primitives while preserving the spectral information that matters?"

The ADFT architecture I implemented uses coefficient approximations that reduce the transform to combinations of:

addition
subtraction
right shifts
routing
registers

For example:

$$ \frac{1}{2}x = x \gg 1 $$

$$ \frac{1}{4}x = x \gg 2 $$

$$ \frac{3}{4}x = x - (x \gg 2) $$

The main ADFT core therefore requires no general-purpose multipliers.

That distinction is important. A constant coefficient that happens to be easy to express in binary is not really a "multiplication problem" anymore. It is an architecture problem.

Start with a Software Reference You Trust

Before building the HDL design, I generated several complex-valued test cases in MATLAB and compared the ADFT response with an FFT reference.

The cases covered three useful spectral situations:

Case A - DC plus bin-aligned tones
Case B - off-bin tones with spectral leakage
Case C - multiple bin-aligned tones with unequal amplitudes

The per-bin energy metric was:

$$ P_k = a_k^2 + b_k^2 $$

where $a_k$ and $b_k$ are the real and imaginary components of each frequency bin.

The point of the MATLAB stage was not to prove that an FFT works.

It gave me a golden reference that stayed unchanged while the hardware implementation evolved.

Later, when something went wrong in Simulink or on the FPGA, I could ask:

Is this an approximation effect, a fixed-point effect, a pipeline-alignment error, or a hardware integration error?

Without a software reference, those failure modes are difficult to separate.

Lesson 1 - A Hardware-Friendly Algorithm Still Needs a Hardware Architecture

The mathematical transform does not specify:

where registers go;
how wide intermediate values should be;
when all outputs become valid;
which paths must be delayed;
how input samples are framed.

Those decisions belong to the architecture.

The HDL Coder interface used sixteen fixed-point inputs:

8 real samples
8 imaginary samples

and produced sixteen outputs:

8 real frequency components
8 imaginary frequency components

The explicit 16-input / 16-output mapping made it easier to compare the mathematical transform, Simulink model, and generated HDL.

I found this explicit mapping useful because it prevented the interface from hiding too much.

Each signal corresponded to a specific part of the complex vector, so debugging a wrong output bin remained manageable.

A simplified design flow was:

flowchart LR
    A["MATLAB Reference"] --> B["Fixed-Point Inputs"]
    B --> C["ADFT Butterfly Network"]
    C --> D["Real and Imaginary Outputs"]
    D --> E["Power per Bin"]
    E --> F["Spectrum Classification"]

I deliberately keep the Mermaid syntax simple here because it is also much more portable across renderers.

Lesson 2 - Pipelining Is Not Just Adding Registers

My first hardware version was functionally correct but had long combinational paths.

Several add/subtract operations could be traversed within one clock period. That created a critical path dominated by chained arithmetic.

The unoptimised critical-path estimate was about:

$$ T_{\text{critical}} \approx 6.93\ \text{ns} $$

After pipelining and delay balancing, the post-implementation path was reduced to approximately:

$$ T_{\text{critical}} \approx 3.13\ \text{ns} $$

The corresponding routed maximum clock frequency increased from roughly:

$$ 146.18\ \text{MHz} $$

to:

$$ 316.86\ \text{MHz} $$

The result was more than a 2x increase in achievable frequency without changing the transform arithmetic itself.

The arithmetic is similar in both designs; the important difference is how the combinational work is segmented by registers.

The lesson was that pipelining has at least three separate jobs.

Breaking the critical path

A register prevents the next combinational stage from belonging to the same timing path.

Instead of:

adder -> adder -> shift -> adder -> register

the architecture becomes closer to:

adder -> register
shift -> register
adder -> register

Balancing data arrival

This part is easier to underestimate.

If one operand reaches an adder after two pipeline stages and another reaches it after three, the arithmetic is wrong even though every individual block is correct.

So shorter paths need explicit delays.

Defining latency as part of the interface

Once the datapath is pipelined, output timing becomes:

input frame
    ↓
pipeline latency
    ↓
valid output frame

Latency is not an implementation detail anymore. Downstream logic has to understand it.

:::important[Pipelining changes time, not the algorithm] The numerical transformation can remain identical while the temporal behaviour of the module changes completely. :::

Lesson 3 - Registers Are Cheap Only If You Remember What They Cost

The pipelined version retained the same basic arithmetic:

56 adders/subtractors
8 static shift operators
0 multipliers in the ADFT core

but the register count increased substantially because of pipeline staging and delay balancing.

That is exactly the expected trade-off:

Design choice	Main effect
Fewer registers	Lower latency and fewer flip-flops, but longer critical paths
More pipeline registers	Higher clock rate and throughput, but more latency and state
More parallel arithmetic	Higher throughput, but more area
Narrower fixed point	Lower storage/routing cost, but more quantisation risk

I used to think of pipelining mainly as a performance technique.

This project made me think of it as a resource exchange:

spend registers and latency to buy timing margin.

That framing is much more useful when comparing architectures.

Lesson 4 - Fixed-Point Design Is Part of the Algorithm

The input samples were represented with a 16-bit fixed-point format using 12 fractional bits.

The difficult part was not writing:

Q1.12

in a block parameter.

The difficult part was making sure intermediate arithmetic did not quietly destroy the spectrum.

I considered several issues:

growth after addition;
temporary guard bits;
truncation points;
rounding mode;
overflow behaviour;
final output compatibility with MATLAB.

A useful model is:

$$ x_{\text{fixed}} = \operatorname{round}(x \cdot 2^F) $$

where $F$ is the number of fractional bits.

Increasing $F$ improves precision, but only until the total word length becomes the limiting factor.

In my numerical sweep, the spectral mean-squared error decreased rapidly as fractional precision increased and reached approximately:

$$ 1.26 \times 10^{-11} $$

at 12 fractional bits.

The precision sweep helped turn a word-length choice into a measurable engineering decision rather than a guess.

This is one of the fixed-point habits I now value most:

Do not choose a format only because it "looks precise enough." Sweep it against a reference and measure the error.

Lesson 5 - FPGA-in-the-Loop Is More Useful Than I Expected

Simulation can confirm the Simulink model.

Synthesis can confirm that the design maps to hardware.

But neither alone proves that the generated FPGA implementation produces the exact sample stream expected by the software model.

That is where FPGA-in-the-loop verification became useful.

MATLAB supplied the fixed-point inputs, the Nexys 4 executed the ADFT hardware, and the returned outputs were compared with the delayed software reference.

The error was evaluated as:

$$ e[n] = y_{\text{FIL}}[n] - y_{\text{ref}}[n] $$

After compensating for the pipeline latency, the error remained zero across the verification window.

Both baseline and optimised designs were compared against the same software reference after compensating for hardware latency.

The key phrase there is after compensating for latency.

Without aligning the streams, even a perfectly correct pipelined design appears wrong.

That reinforced a recurring FPGA lesson for me:

Correct values at the wrong clock cycle are still incorrect hardware behaviour.

Lesson 6 - Timing Reports Tell You More Than "Pass" or "Fail"

It is tempting to treat timing analysis as binary:

timing passed
timing failed

But the more useful question is:

What physical structure created the critical path?

In the unoptimised version, the dominant path passed through several arithmetic operations before reaching a register.

That told me exactly what to optimise.

After pipelining, the longest path was reduced to roughly one arithmetic stage between registers.

The main timing comparison was:

Metric	Unoptimised	Optimised
HDL critical-path estimate	~6.93 ns	~3.30 ns
Post-implementation delay	~6.87 ns	~3.13 ns
Post-implementation Fmax	~146.18 MHz	~316.86 MHz
ADFT multipliers	0	0
ADFT arithmetic structure	add/shift	add/shift

The important observation is that the frequency gain did not come from replacing the algorithm.

It came from changing the spatial and temporal structure of the same arithmetic.

Lesson 7 - Verification Should Follow the Same Test Cases Across Every Layer

I reused the same representative spectra across:

MATLAB
Simulink functional simulation
FPGA-in-the-loop
standalone FPGA testing

That consistency was extremely valuable.

Representative spectra were kept consistent across software and hardware verification.

Changing test signals at every stage makes each verification step individually interesting but weakens the end-to-end argument.

Using the same cases lets you trace one expected behaviour through the entire toolchain:

known input spectrum
      ↓
software ADFT
      ↓
fixed-point Simulink
      ↓
generated HDL
      ↓
FPGA-in-the-loop
      ↓
physical board

This is a verification strategy I would reuse in future hardware projects.

Lesson 8 - A Standalone FPGA System Needs Much More Than the Compute Core

Once the ADFT itself worked, the final task was turning it into a standalone spectrum-sensing pipeline.

The complete signal path was:

flowchart LR
    ROM["Real and Imag ROM"] --> SIPO["8-Sample SIPO"]
    SIPO --> ADFT["Pipelined ADFT Core"]
    ADFT --> PWR["Power Calculation"]
    PWR --> CLASS["Low Mid High Classification"]
    CLASS --> SSD["8-Digit SSD Driver"]

The ROM stored pre-generated complex samples.

The SIPO registers converted sequential samples into the 8-sample parallel frame expected by the transform.

The power block calculated:

$$ P_k = a_k^2 + b_k^2 $$

and then classified each bin relative to the maximum energy.

The thresholds used were:

$$ T_{\text{mid}} = 0.25P_{\max} $$

$$ T_{\text{high}} = 0.60P_{\max} $$

Finally, the eight seven-segment digits represented the eight frequency bins.

Each digit used a simple visual encoding:

top segment    -> High
middle segment -> Mid
bottom segment -> Low

I like this architecture because every block has a narrow responsibility.

The ADFT does not know anything about seven-segment displays.

The display driver does not know anything about Fourier transforms.

That separation made the standalone design much easier to debug.

Lesson 9 - The Peripheral Logic Can Be Small but Still Define the Product

The complete system used only a small fraction of the Artix-7 fabric.

The final implementation occupied roughly:

1896 LUTs       ~2.99%
1991 flip-flops ~1.57%
1 BRAM tile
16 DSP slices in the power-computation stage

The ADFT core itself remained multiplierless; the DSP slices in the complete design were associated with the later power calculation.

This distinction matters.

When describing an FPGA design, saying:

"The system uses DSP slices"

is not the same as saying:

"The transform requires multipliers."

Architecture-level resource attribution is more informative than quoting only a top-level utilisation number.

On-Board Results Made the Design Feel Real

The final system ran on the Nexys 4 without MATLAB continuously controlling it.

The eight seven-segment displays provide a coarse but immediate view of the relative energy distribution across the eight frequency bins.

The three test cases produced the expected Low/Mid/High patterns on the board.

At that point the system had become:

ROM
 -> SIPO
 -> ADFT
 -> power
 -> classification
 -> display

with deterministic timing inside one FPGA clock domain.

This final integration was important because a transform core that passes a unit test is not yet a useful embedded signal-processing system.

The interfaces around it determine whether it can actually consume data and expose a meaningful result.

What I Would Change in a Second Version

1. Add explicit valid/ready signalling

The laboratory version used a deterministic framing structure, but a more reusable core should expose interface-level timing explicitly.

I would prefer something closer to:

input_valid
input_ready
output_valid

rather than relying only on known cycle counts.

2. Parameterise transform width and data format

Instead of fixing everything around one 8-point, 16-bit configuration, I would separate:

transform size
word length
fractional length
pipeline depth

into configurable parameters where practical.

3. Compare energy and power directly

The ADFT reduces arithmetic complexity, but a serious low-power study should measure:

dynamic power
static power
energy per frame
throughput per watt

rather than inferring efficiency from resource counts alone.

4. Stream real input data

The ROM-based test system is excellent for reproducibility.

A natural next step would replace the ROM source with:

ADC
RF front end
DMA/data stream

so that the design performs spectrum sensing on live samples.

5. Make the verification harness automatic

I would build one script that:

generates the MATLAB test vector;
exports the fixed-point ROM data;
runs HDL/FIL verification;
compensates latency automatically;
computes error metrics;
produces the comparison figures.

That would make architecture iteration much faster.

Final Thoughts

This project changed how I think about FPGA optimisation.

At first, the most interesting idea seemed to be the multiplierless ADFT itself.

By the end, I found the architectural lessons more valuable:

a hardware-friendly equation is only the beginning;
pipelining is a deliberate exchange between timing, latency, and registers;
delay balancing is just as important as inserting registers;
fixed-point precision should be measured, not guessed;
verification has to account for time as well as value;
resource reports are most useful when interpreted by module;
a compute core becomes useful only after it is integrated into a complete data path.

The biggest lesson I kept is:

FPGA performance often improves not because the arithmetic changes, but because the same arithmetic is reorganised in space and time.

That idea now influences how I look at DSP accelerators, hardware pipelines, and almost any architecture intended for real-time FPGA implementation.

Building a Wireless FreeRTOS Controller for a Remote Microscope

GuanHua Yu — Thu, 20 Aug 2026 00:00:00 GMT

Building a Wireless FreeRTOS Controller for a Remote Microscope

One of the projects that changed the way I think about embedded software was a wireless controller for a Remote Controlled Microscope (RCM).

The physical system was much larger than the microcontroller sitting on my desk. The RCM was based on an X-Carve-style CNC platform, with stepper motors controlling the microscope position over a roughly 200 mm by 200 mm work area. The controller had to select commands locally, package them into a wireless protocol, send them through an nRF24L01+ radio link, and keep several local displays and indicators synchronized with the current command state.

The RCM turns embedded commands into movement of a real three-axis physical system.

The project used a Nucleo-F429ZI, an MFS board, an RGB LED, and an nRF24L01+ transceiver. What made the project interesting was not any one peripheral. It was the need to combine FreeRTOS scheduling, finite-state machines, interrupt-driven inputs, wireless communication, packet encoding, and physical-system control into one coherent architecture.

I came away from this project with a much stronger appreciation for one idea:

In a larger embedded system, the hardest problem is usually not writing a driver. It is deciding which module is allowed to own which responsibility.

The System Was a Chain of Responsibilities

At a high level, the controller had to turn physical input into a radio command.

The path was conceptually:

Pushbuttons / switchbank / trimpot
        ↓
Command selection
        ↓
Command execution
        ↓
RCM state update
        ↓
Packet construction
        ↓
Hamming encoding
        ↓
TX queue
        ↓
nRF24L01+ radio
        ↓
Remote microscope

At the same time, the controller had local output responsibilities:

current command
    ↓
7-segment display
LED bar opcode
RGB status
diagnostic LEDs

That meant the design was not a single loop anymore. It was a set of cooperating state machines and FreeRTOS tasks.

My top-level flow separated startup, button events, command processing, packet construction, and radio transmission.

Lesson 1 - FreeRTOS Is Most Useful When It Defines Ownership

It is easy to think that the reason to use an RTOS is simply to "run several things at once."

That is only part of the benefit.

What I found more useful was that FreeRTOS encouraged me to decide which task owned each resource.

For example, the radio transmitter should be responsible for the radio.

The command-input module should not directly manipulate radio registers just because it knows that a packet needs to be sent.

Instead, the cleaner relationship is:

command task
    ↓
RCM system logic
    ↓
TX queue
    ↓
radio task

This creates a boundary.

The command task knows what should happen.

The radio task knows how to transmit it.

That difference became increasingly important as the project grew.

If every task can directly call every peripheral, then adding an RTOS can actually make the architecture harder to understand. Concurrency without ownership just creates more possible interactions.

Lesson 2 - Queues Are More Than Buffers

The TX queue was one of the most important architectural boundaries in the project.

A packet producer could construct a command without caring whether the radio was currently idle, configuring its channel, waiting for the nRF24L01+ state machine, or loading a transmit FIFO.

The producer only needed to place a valid packet into the queue.

The radio side could then process packets at its own pace.

That turns the queue into a contract:

Producer guarantee:
"I will give you complete packets."

Consumer guarantee:
"I will transmit them in the correct radio context."

This is much easier to reason about than a design where command code immediately starts an SPI transaction.

It also makes failures easier to isolate.

If no packet appears on air, I can ask:

Was the packet created?
Did it reach the queue?
Did the radio task dequeue it?
Did the nRF24L01+ enter TX mode?

Each question belongs to a different layer.

Lesson 3 - The Radio Has Its Own State Machine

The nRF24L01+ is controlled through SPI and exposes control registers, TX/RX FIFOs, a CE control pin, and several radio states.

The nRF24L01+ provides the wireless link while the MCU controls configuration and data transfer over SPI.

The module operates at 2.4 GHz and supports data rates up to 2 Mbps. SPI is used both for configuration and for moving payload data into or out of the radio FIFOs.

This is important because "send packet" is not a primitive physical action.

The software has to coordinate:

radio configuration
channel
address
FIFO state
CE control
TX state
return to idle

My radio-control FSM reflected that separation.

The radio path verifies configuration, handles JOIN ownership, and then processes command packets through dedicated states.

This project reinforced a useful rule for peripheral drivers:

If the hardware itself is stateful, pretending that it is a stateless function call usually makes the software worse.

A finite-state machine makes the legal transitions explicit.

Lesson 4 - JOIN Was Really an Ownership Protocol

Before normal control packets could be accepted, the controller had to send a JOIN packet.

At first, this looked like just another command.

It is more useful to think of it as a distributed ownership mechanism.

The rule is essentially:

JOIN
  ↓
RCM associates control with this sender
  ↓
XYZ / ZOOM / BRIGHT commands become valid

Without a valid JOIN, the RCM rejects subsequent control packets.

This solves an important physical-system problem: multiple users should not independently move the same microscope at the same time.

That made the protocol feel much more real to me.

The packet is not only carrying data. It is establishing permission to affect a physical machine.

In a networked embedded system, protocol design and safety boundaries can become the same problem.

Lesson 5 - Packet Structure Should Be Stable Before the Tasks Become Complicated

The project used a fixed radio packet structure with:

packet type
sender address
payload string
padding

A raw packet was 16 bytes.

Each half-byte was then Hamming encoded, producing a 32-byte radio packet.

Conceptually:

16-byte raw packet
       ↓
split each byte into two nibbles
       ↓
Hamming encode each nibble
       ↓
32-byte encoded packet
       ↓
TX queue

The major packet types included:

Type	Purpose
`JOIN`	Acquire control of the RCM
`XYZ`	Set absolute X, Y and Z coordinates
`ZOOM`	Set/change microscope zoom
`BRIGHT`	Adjust image brightness

For an XYZ packet, the coordinates are expressed as decimal ASCII fields. That makes the payload relatively easy to inspect during debugging.

I liked the separation between semantic payload and radio representation.

The command layer can think in terms of:

X = 100 mm
Y = 0 mm
Z = 0 mm

while the packet layer is responsible for turning that meaning into the exact byte layout required on air.

That boundary is worth protecting.

Lesson 6 - Error-Correcting Codes Change the Way You Think About Interfaces

Hamming encoding was another part that initially looked like a small implementation detail.

It became more interesting when I thought about where it belongs.

The command logic should not care that a nibble is being protected by an error-correcting code.

Similarly, the radio driver should not need to understand that the payload represents an X coordinate.

A cleaner stack is:

RCM command
    ↓
raw protocol packet
    ↓
Hamming encoding
    ↓
radio transport

Each layer transforms the representation while preserving the meaning.

This same idea appears in much larger communication systems.

Once I started viewing it that way, embedded networking became less about "sending bytes" and more about building a protocol stack, even if the stack is small.

Lesson 7 - Interrupts Should Wake Work, Not Become the Work

Pushbuttons are asynchronous.

The tempting approach is to detect a button interrupt and immediately perform the entire action inside the interrupt handler.

That becomes dangerous when the action eventually includes:

state-machine updates
display changes
packet creation
Hamming encoding
queue operations
radio transmission

The better design is to let the interrupt communicate an event to a task.

My overall flow used FreeRTOS synchronization to move from a button event into task-level processing.

Button events are translated into synchronization signals that drive the higher-level command state machine.

This is one of the most important habits I took from the project.

An ISR should ideally answer:

"What happened?"

and then wake the code that decides:

"What should the system do about it?"

Those are different responsibilities.

Keeping that boundary clear improves latency, predictability, and maintainability.

Lesson 8 - A Command FSM Makes a Small User Interface Predictable

The local user interface had only a few physical inputs:

a command-selection pushbutton;
an execute pushbutton;
an 8-bit switchbank value;
a trimpot for relative settings.

But those inputs could control several behaviours:

X
Y
Z
ZOOM
BRIGHT
ORG

A state machine was a natural way to map repeated CMD presses into a selected operation.

The command task separates selecting an operation from executing it and constructing the corresponding packet.

This is much cleaner than writing a long list of unrelated button checks.

The state machine answers:

What command is currently selected?

The execute event answers:

When should the selected command take effect?

The switchbank or trimpot answers:

What value should that command use?

Separating those three ideas reduced ambiguity.

Lesson 9 - Input Conversion Deserves Its Own Task Boundary

The switchbank provided an 8-bit input value.

One of my task flows periodically read the GPIO state, converted the raw binary input to a decimal representation, formatted it for the rest of the system, and then returned to a periodic wait.

The switchbank task turns raw GPIO state into a reusable numeric value rather than exposing pin-level details to command logic.

This may look like a small wrapper around GPIO.

But it represents an important software boundary:

hardware representation:
8 GPIO bits

application representation:
VALUE

The command FSM should care about VALUE, not individual pins.

That same principle scales to sensors, ADCs, network packets, and almost every embedded interface.

Lesson 10 - Local Indicators Are Extremely Valuable in Distributed Debugging

A wireless physical system can fail in many places.

A command might be selected correctly but never executed.

A packet might be created correctly but never transmitted.

The radio might transmit but the RCM might reject the sender.

Without local observability, all of these failures can look like:

"The microscope did not move."

The project therefore used several local indicators:

MFS D1      -> packet transmission activity
MFS D2      -> pushbutton activity
LED bar     -> selected command opcode
7-segment   -> current command value
RGB LED     -> zoom/brightness direction or default state

My output FSM coordinated those displays.

The local-output logic maps command state to the seven-segment display, LED bar, and RGB indicator.

This made me appreciate diagnostic outputs as part of architecture rather than decoration.

A spare LED can sometimes save more debugging time than another hundred lines of logging code.

Lesson 11 - Absolute Motion Commands Simplify the Distributed State

The RCM uses an absolute coordinate frame for X, Y, and Z.

The work area is approximately:

$$ 200\text{ mm} \times 200\text{ mm} $$

with an origin at the lower-left of the operating area.

A command such as:

XYZ10000000

describes a target state rather than a movement history.

That has a useful property in a remote-control system.

With relative commands:

move +10
move +10
move -5

the sender and receiver must remain synchronized about the current position.

With absolute commands:

go to X = 100

the desired final state is explicit.

That does not eliminate every synchronization problem, but it reduces how much history has to be shared between the controller and the machine.

The Architecture Became Easier to Understand as Several FSMs

By the end of the project, I was not thinking in terms of one giant state machine.

I had several smaller behavioural models:

Command FSM
    -> what the user is selecting

Radio FSM
    -> how packets reach the air

Output FSM
    -> what local feedback should be shown

RCM processing flow
    -> how received command types affect the machine

FreeRTOS synchronization
    -> how events move between those modules

The receive-side flow also made the protocol layering visible.

JOIN, XYZ, ZOOM, and BRIGHT commands follow different paths but eventually converge on shared output and waiting states.

A single giant FSM would have created too many transitions.

Multiple smaller FSMs allowed each module to describe one domain.

This is a design pattern I still prefer:

Use state machines to describe local behaviour, and use queues/events to connect the machines.

What I Would Improve in a Second Version

If I rebuilt the controller now, I would keep the overall task separation but make several parts more explicit.

1. Add an application-level acknowledgement

The radio can indicate transport-level success, but for a physical system I would also like to know that the remote application accepted and applied the command.

Conceptually:

command
    ↓
radio transmission
    ↓
remote validation
    ↓
ACK with command sequence number

That would make it easier to distinguish radio delivery from physical command acceptance.

2. Add sequence numbers

A sequence number would help detect:

duplicates
stale packets
out-of-order application messages

especially if the protocol were expanded.

3. Centralise system state

I would keep one explicit RCM state model containing:

X
Y
Z
zoom
brightness
ownership status
last command

and let display and packet-generation tasks consume snapshots or messages derived from it.

4. Make task interfaces more strongly typed

Instead of moving generic byte arrays between every layer, I would use small message structures internally and only serialize them at the packet boundary.

That would make invalid states harder to represent.

5. Instrument queue and task timing

For a FreeRTOS system, I would add lightweight runtime measurements for:

queue depth
task execution time
radio service latency
command-to-transmit latency
stack high-water marks

This would make performance tuning much more quantitative.

Final Thoughts

This project was a useful transition from peripheral-level embedded programming to system-level embedded architecture.

The nRF24L01+ driver mattered.

The FreeRTOS APIs mattered.

The Hamming encoder mattered.

But the deeper lessons were about how those pieces should be connected.

I learned to think more carefully about:

task ownership;
queues as module boundaries;
interrupts as event sources;
protocol layers;
finite-state machines;
synchronization primitives;
diagnostic observability;
the difference between raw hardware values and application-level state.

The physical microscope made those decisions feel much more consequential.

If a small LED demo has a race condition, an LED flashes incorrectly.

If a distributed controller has a confused state model, a physical machine may move somewhere the operator did not intend.

The biggest lesson I kept from the RCM project is:

A reliable embedded system is built by controlling not only the hardware, but also the flow of responsibility between software components.

That idea has become one of the main ways I evaluate embedded architectures today.

Building Sokoban on an AVR: From Game Logic to Real-Time Peripheral Integration

GuanHua Yu — Thu, 20 Aug 2026 00:00:00 GMT

Building Sokoban on an AVR: From Game Logic to Real-Time Peripheral Integration

Sokoban is not a complicated game to explain.

A player walks around a warehouse, pushes boxes, and tries to place every box on a target. There are no enemies, no physics engine, and no complicated graphics. That simplicity makes it a surprisingly useful embedded-systems project, because almost all of the difficulty comes from state, timing, I/O, and hardware interaction rather than visual complexity.

I built my version on an ATmega324A in C. The game state was shown on a 16x8 LED matrix, while the same system also interacted with physical push buttons, a serial terminal, a joystick, a two-digit seven-segment display, and a piezo buzzer.

What started as a small puzzle game became a compact exercise in embedded architecture.

The warehouse can be reduced to a small number of object types: player, walls, boxes, targets, and empty space.

The most useful lesson was that a game on a microcontroller is not really about drawing pixels. It is about keeping one consistent state while many peripherals observe or modify it.

The Hardware Was Simple; the State Was Not

The project used a small warehouse map rendered on the LED matrix.

At a logical level, the world only needs a few concepts:

Wall
Target
Box
Player
Empty

But some cells contain overlapping meaning.

For example:

player + target
box + target

If I represented the screen only as colours, the implementation quickly became awkward. A green pixel could mean a player, a box on a target, or part of an animation.

The better mental model is to separate game state from render state.

flowchart LR
    Input["Buttons / UART / Joystick"] --> Logic["Movement and Collision Logic"]
    Logic --> State["Game State"]
    State --> Matrix["LED Matrix Renderer"]
    State --> Terminal["Terminal Renderer"]
    State --> SevenSeg["Step Counter"]
    State --> Sound["Sound Events"]

The LED matrix is only one view of the game.

That distinction sounds obvious now, but it was one of the first embedded projects where I clearly saw why separating model and presentation matters.

Lesson 1 - Do Not Let Display State Become Game State

A tempting implementation is:

if (pixel_is_yellow(next_x, next_y)) {
    // wall
}

It works until colours begin to carry multiple meanings.

Targets may flash. A player can stand on a target. A box on a target uses a different colour. The terminal may use a different colour palette from the physical LED matrix.

Instead, movement should operate on the logical warehouse representation:

if (is_wall(next_position)) {
    reject_move();
}
else if (has_box(next_position)) {
    try_push_box();
}
else {
    move_player();
}

Rendering happens afterwards.

Conceptually:

Game State
    ↓
render_led_matrix()
render_terminal()
update_seven_segment()

This has an important property:

A change in visual representation does not change the rules of the game.

That becomes especially valuable once animation and alternate displays are introduced.

The same game can be represented through different output surfaces without changing the underlying state.

Lesson 2 - One Movement Function Should Serve Every Input Device

The project supported movement from more than one interface.

I used:

physical push buttons;
serial terminal input;
a 2-axis joystick.

The terminal used conventional W/A/S/D controls, while the buttons mapped directly to the four cardinal directions.

At first, it is easy to write separate logic:

button right -> move right
terminal 'd' -> move right
joystick east -> move right

The problem appears when collision logic becomes more complicated.

If each interface implements its own movement behaviour, eventually one input method handles a box differently from another.

A better structure is:

flowchart TD
    B["Push Button"] --> D["Direction Command"]
    U["UART Character"] --> D
    J["Joystick Position"] --> D
    D --> M["move_player direction"]
    M --> C{"Collision"}
    C -->|Wall| W["Reject"]
    C -->|Box| P["Try Push"]
    C -->|Free| V["Move"]

Every frontend should translate physical input into a common command.

For example:

typedef enum {
    MOVE_UP,
    MOVE_DOWN,
    MOVE_LEFT,
    MOVE_RIGHT
} direction_t;

Then:

handle_button_input();
handle_uart_input();
handle_joystick_input();

can all eventually call the same game-logic function.

This was one of the earliest projects where I learned a principle that I later found useful in much larger systems:

Hardware interfaces should terminate at a clean software boundary.

Lesson 3 - Sokoban Collision Logic Is a Small State Machine

Walking into empty space is easy.

Pushing boxes is where the game becomes interesting.

A requested movement can result in several different outcomes:

1. Empty cell        -> player moves
2. Target            -> player moves onto target
3. Wall              -> movement rejected
4. Box + free space  -> box moves, then player moves
5. Box + wall        -> movement rejected
6. Box + box         -> movement rejected
7. Box + target      -> box becomes box-on-target

I found it much easier to reason about this as a decision sequence rather than as scattered special cases.

flowchart TD
    A["Requested Move"] --> B{"Destination"}
    B -->|Wall| X["Reject"]
    B -->|Empty or Target| M["Move Player"]
    B -->|Box| C{"Cell Behind Box"}
    C -->|Wall| X
    C -->|Box| X
    C -->|Empty or Target| P["Push Box"]
    P --> M

A valid push, a blocked wall case, and a blocked box case can all be handled by the same movement-validation path.

A useful detail is to avoid modifying the world until the move has been validated.

In other words:

calculate destination
calculate box destination if needed
validate entire move
commit changes
render

rather than:

move player
discover collision
undo part of the move
fix display

The first approach produces much cleaner state transitions.

It also makes step counting easier because only a valid committed move should increment the count.

Lesson 4 - Wraparound Makes Coordinate Logic Worth Centralising

The game board allowed movement across the display boundary.

A player walking off one side appears on the opposite side.

For a board with width $W$ and height $H$:

$$ x' = (x + \Delta x + W) \bmod W $$

$$ y' = (y + \Delta y + H) \bmod H $$

The extra +W or +H avoids a negative value before the modulo operation.

This looks like a small implementation detail, but centralising it mattered because wrapping applies not only to the player.

If a player pushes a box at an edge, the box's destination also has to be evaluated using the same coordinate rules.

A helper such as:

position_t wrap_position(int x, int y);

is safer than reproducing boundary conditions inside every collision case.

Small helpers like this reduce the number of places where hardware-constrained C code can quietly go wrong.

Lesson 5 - Real-Time Does Not Mean "Use Delay Everywhere"

The player icon flashes.

Targets can animate.

The level timer updates.

A buzzer may be producing a tone.

The system must still accept input.

This is where blocking delays become dangerous.

A simple implementation such as:

turn_player_on();
_delay_ms(200);
turn_player_off();
_delay_ms(200);

makes the animation correct but the game unresponsive.

The better pattern is to compare timestamps:

if (now_ms - last_flash_ms >= FLASH_INTERVAL_MS) {
    player_visible = !player_visible;
    last_flash_ms = now_ms;
}

Now the main loop can continue processing:

buttons
UART
joystick
game logic
display
sound

between animation events.

The difference is fundamental:

Blocking timing:
do task -> wait -> continue

Non-blocking timing:
check time -> update if due -> continue immediately

This project was one of my first practical examples of why embedded timing should usually be event-driven rather than delay-driven.

:::important[Responsiveness is a system property] A function can be individually correct and still make the system wrong if it blocks every other feature while it runs. :::

Lesson 6 - Pause Is More Complicated Than Freezing the Main Loop

A pause feature looks trivial until timing state is involved.

If the game pauses halfway through a 200 ms flash cycle, resuming should continue from that point rather than restarting the animation.

Similarly, the level timer should exclude paused time.

That means the program needs to distinguish between:

wall-clock time

and:

active gameplay time

One simple model is:

$$ T_{\text{game}} = T_{\text{now}}

T_{\text{start}}

T_{\text{paused,total}} $$

When pausing:

pause_start = now

When resuming:

total_paused += now - pause_start

This was a useful introduction to a broader real-time concept:

Time is part of program state.

Once timers, animations, and sound depend on elapsed time, "pause" is not merely a boolean.

Lesson 7 - Multiple Displays Should Read from the Same Source of Truth

The project had three very different output paths:

the 16x8 LED matrix;
a serial terminal view;
a two-digit seven-segment step counter.

The terminal was especially useful because it provided a second representation of the same game and doubled as a debugging interface.

The correct architecture is:

update_game_state();

render_led_matrix();
render_terminal();
render_step_count();

If the terminal renderer tries to infer state from the LED output buffer, the software layers become unnecessarily coupled.

The terminal also taught me something useful about bandwidth.

A serial interface is slow compared with writing memory. Redrawing the entire display every loop wastes bandwidth and can create visible latency.

So the correct question is not:

Can I print the display?

It is:

How often does the display actually need to change?

That same reasoning applies to embedded dashboards, HMIs, and network telemetry.

Lesson 8 - Multiplexing a Seven-Segment Display Is a Timing Problem

The step counter used a two-digit seven-segment display.

The visual output wraps at two decimal digits even though the internal step count remains larger.

Two digits are commonly multiplexed:

show tens
disable
show ones
disable
repeat quickly

If the refresh is too slow, the digits flicker.

If both digits are switched incorrectly, ghosting appears.

If display refreshing is performed with blocking code, gameplay responsiveness suffers.

So even a tiny seven-segment display becomes another scheduled real-time task.

The value displayed was only the lower two digits:

$$ D = S \bmod 100 $$

where $S$ is the full step count.

Importantly, the internal step count should not itself wrap at 100 because the final game score may need the true number of steps.

This is another example of the difference between:

internal state

and:

display representation

Lesson 9 - Joystick Input Exposes Weak Movement Abstractions

Adding a joystick changed the movement problem.

Cardinal movement is one step:

north
south
east
west

But a diagonal joystick direction represents two orthogonal steps.

Two possible intermediate paths can produce the same diagonal result, so the intermediate collision state matters.

For example, north-east can be decomposed as:

east -> north

or:

north -> east

The intermediate square matters because a wall may block one ordering but not the other.

The project rules also disallowed diagonal box pushes.

This feature exposed whether movement logic was truly reusable.

If the basic movement routine is clean, diagonal movement can reuse it.

If movement and input handling are tangled together, the joystick feature forces a major rewrite.

That was a useful architecture test.

A feature that should be an extension becomes difficult when the original abstraction was wrong.

Lesson 10 - Sound Effects Must Be Asynchronous

The piezo buzzer added feedback for game events such as movement, invalid moves, box actions, startup, or game completion.

The easiest implementation is also the worst:

tone(440);
_delay_ms(100);
tone(660);
_delay_ms(100);

Now input handling stops for 200 ms.

A better sound engine keeps track of:

current tone
tone duration
sequence index
next update time
mute state

and advances the sequence from the normal event loop.

Conceptually:

stateDiagram-v2
    [*] --> Idle
    Idle --> Playing: sound event
    Playing --> Playing: next tone
    Playing --> Idle: sequence complete
    Playing --> Paused: game paused
    Paused --> Playing: resume

The important idea is not audio itself.

It is that every new peripheral is another asynchronous activity competing for the MCU.

Level Completion Is a Good Test of State Consistency

A level is complete when every target contains a box.

The final state should be internally consistent before the victory screen is shown.

At level completion, every target contains a box and the remaining state can be used to calculate statistics.

The score combines step count and elapsed time:

$$ \text{Score}

\max(200-S,0)\times20 + \max(1200-T,0) $$

where:

$S$ is the full number of steps;
$T$ is elapsed gameplay time in seconds.

This was another reason not to let UI representations replace the underlying state.

The seven-segment display may show:

but the real step count could be:

The gameplay model must keep the full value.

The project also introduced a second level, which is a good reminder that level data should be treated as data rather than hard-coded behaviour.

A second layout uses the same engine but different initial world data.

The Architecture I Would Use Today

If I rewrote the project now, I would structure it into four layers.

flowchart TB
    HW["Hardware Drivers: SPI, UART, ADC, GPIO, Timer"]
    IN["Device Services: Buttons, Joystick, Matrix, Sound"]
    GAME["Game Engine: Movement, Boxes, Targets, Victory"]
    APP["Application State: Start, Playing, Paused, Game Over"]
    APP --> GAME
    GAME --> IN
    IN --> HW

Hardware drivers

Responsible only for things such as:

SPI
UART
GPIO
ADC
timers
PWM

Device services

Translate hardware into useful concepts:

read_joystick_direction()
button_pressed()
display_board()
set_step_count()
play_sound()

Game engine

Should know nothing about AVR registers.

It should operate on:

positions
walls
boxes
targets
moves

Application state machine

Controls:

START
PLAYING
PAUSED
GAME_OVER

This separation would make the game logic much easier to test on a PC without any hardware.

:::tip[The test I now use for embedded architecture] If a pure logic module cannot be compiled without including MCU register headers, hardware and application logic are probably too tightly coupled. :::

What I Would Improve in a Second Version

1. Use explicit event objects

Instead of output modules checking the game state independently, the game engine could emit events:

PLAYER_MOVED
MOVE_REJECTED
BOX_PUSHED
BOX_ON_TARGET
LEVEL_COMPLETE

The sound and UI systems could react without being embedded inside the movement code.

2. Create a single scheduler for periodic tasks

Rather than giving every feature its own ad-hoc timing checks, I would centralise periodic scheduling for:

player flashing
target animation
seven-segment multiplexing
sound sequencing
level-time refresh

3. Unit-test the movement engine on a computer

Collision rules are deterministic and do not require real hardware.

I would create small board states and test cases such as:

push box into wall -> rejected
push box onto target -> valid
walk through edge -> wrapped
diagonal joystick move into box -> rejected

4. Keep peripheral code extremely small

The more work that happens inside interrupt handlers and device drivers, the harder the whole game becomes to reason about.

5. Treat debugging interfaces as first-class features

The UART terminal was useful not only as a user interface but also as a debugging window into the system.

In future embedded projects, I would deliberately design diagnostics instead of adding printf() calls only when something breaks.

Final Thoughts

This project was small enough that I could understand almost every line of the system, but large enough to expose the problems that appear when multiple peripherals share one microcontroller.

I started the project thinking mainly about C and AVR registers.

I finished it thinking much more about:

state ownership;
abstraction boundaries;
non-blocking timing;
reusable input paths;
deterministic game rules;
multi-display consistency;
peripheral scheduling.

That shift mattered more than any individual feature.

The LED matrix, joystick, terminal, seven-segment display, and buzzer were all useful, but the real engineering challenge was making them behave as one coherent system.

The lesson I kept from Sokoban is:

On a microcontroller, complexity rarely comes from one difficult algorithm. It comes from many simple things needing to remain correct at the same time.

That idea has followed me into every larger embedded and real-time project I have worked on since.

Building a Multithreaded Chess Server in C: TCP, Threads, Pipes, and Stockfish

GuanHua Yu — Thu, 20 Aug 2026 00:00:00 GMT

Building a Multithreaded Chess Server in C: TCP, Threads, Pipes, and Stockfish

A chess server is a surprisingly good systems-programming project.

At first glance, the application sounds simple:

connect a client
receive a move
check the move
send a response

The interesting part appears when the requirements become more realistic.

Several clients may be connected at the same time. Some want to play the computer, while others want to be paired with another human. The chess engine is a separate process. Network communication is asynchronous. A human opponent can disconnect halfway through a game. The server has to retain game state, serialize access to shared resources, and continue running even when one connection disappears.

That turns a chess application into a compact exercise in:

TCP networking
POSIX threads
process creation
pipes and file descriptors
inter-process communication
mutual exclusion
protocol parsing
shared state
failure handling

The main lesson I took from this project was not about chess.

It was about where state should live when several independently executing parts of a program need to cooperate.

Multiple TCP sessions are handled concurrently, while game state and the single chess-engine process are shared resources.

The Architecture Has Three Different Kinds of Concurrency

I found it useful to separate the problem into three concurrency domains.

1. Client-side asynchrony

The client has two independent input sources:

stdin
network socket

A user may type a command while a server message is arriving.

2. Server-side client concurrency

Every connected client has an independent network session.

The server therefore needs to make progress on many sockets at the same time.

3. Process-level concurrency

The chess engine is not a library call.

Stockfish is a separate process with its own stdin and stdout, connected to the server with pipes.

These look similar because all three involve "multiple things happening", but they require different abstractions.

That distinction helped me avoid treating every problem as simply another thread.

Lesson 1 - A Network Client Has to Listen in Two Directions

A blocking command-line client is easy to imagine:

read user input
send request
wait for reply
repeat

That model assumes every message from the server is a direct reply to the most recent request.

A multiplayer game breaks that assumption.

If another human player makes a move, the server can send a message even though the local user did not just type anything. A game can also end because the other player resigns or disconnects.

So the client really has two independent flows.

One path reads commands from stdin.

The other continuously reads messages from the TCP connection.

The client itself should remain relatively thin. It does not need to understand the whole board. It only needs enough local state to decide whether commands such as move, hint, or resign are currently meaningful.

For example:

game in progress?
my turn?
my colour?

The authoritative chess position belongs on the server side.

This gave me a useful distributed-systems rule:

A client should store only the state it needs to provide its interface. The authoritative state should live where decisions are validated.

Lesson 2 - Text Protocols Are Excellent for Debugging

The client and server communicate over TCP using a line-oriented text protocol.

Typical messages can be thought of as:

start computer white
start human either
move e2e4
hint best
hint all
board
resign

and responses as:

started white
ok
moved e7e5
check
moves ...
gameover ...

For a student project, a text protocol has a major advantage: it is observable.

I can connect with a simple terminal tool and manually send commands.

That lets me test the server independently from my own client implementation.

This is an underrated design property.

When both sides of a protocol are being developed at the same time, a human-readable wire format makes it much easier to answer:

Is the problem in the client, the server, or the protocol?

Binary protocols may be more compact, but debuggability has real engineering value.

Lesson 3 - One Thread Per Client Is Simple Until State Becomes Shared

The server accepts incoming TCP connections and creates one handler thread for each client.

That is conceptually straightforward:

accept connection
    ↓
spawn handler thread
    ↓
read command
process command
send response
repeat

The difficulty appears when threads stop being independent.

Two client threads may refer to the same human-vs-human game.

Many client threads may need the same Stockfish process.

Several threads may access the waiting-player list.

At that point, the important question is no longer:

How many threads do I have?

It becomes:

Which data can be touched by more than one thread?

Every shared object needs a clearly defined synchronization policy.

A large mutex around everything may be correct but unnecessarily restrictive.

No mutex at all may work in simple tests and fail unpredictably under simultaneous connections.

The architecture gets much easier to reason about when shared resources are listed explicitly:

connected-client registry
human-matchmaking pool
shared Game objects
Stockfish stdin/stdout transaction

Lesson 4 - A Single Chess Engine Becomes a Serialized Service

One of the most interesting constraints was that the server uses one Stockfish process even while supporting multiple clients and games.

That means the engine cannot safely be treated as if every client thread owns its own private chess library.

Suppose two threads do this at the same time:

Thread A:
position <game A>
go ...

Thread B:
position <game B>
go ...

If those command sequences interleave, the response no longer has an unambiguous owner.

The engine interaction therefore has to be treated as a transaction:

lock engine
set game context
send UCI command
read complete response
unlock engine

The engine lock is not merely protecting a file descriptor.

It protects the semantic integrity of a request-response conversation.

That distinction matters.

Many concurrency bugs happen because programmers lock individual writes but forget that a protocol operation consists of several ordered writes and reads.

Lesson 5 - Pipes Turn a Program into a Service

Stockfish runs as a child process.

The server creates two pipes:

server -> Stockfish stdin
Stockfish stdout -> server

then forks, redirects file descriptors in the child, and launches the engine.

The startup sequence also has a small protocol of its own.

Conceptually:

start process
    ↓
isready
    ↓
readyok
    ↓
uci
    ↓
uciok

This was one of the parts of the project I liked most because it connects several Unix concepts that can otherwise feel unrelated:

pipe()
fork()
dup / descriptor redirection
exec()
FILE* or descriptor I/O
process lifecycle

The result is effectively a local service boundary.

Stockfish could have been a library, but using a process gives useful isolation:

the engine has its own address space;
it can be replaced independently;
communication is constrained to a documented protocol;
engine termination can be detected through the pipe.

Lesson 6 - FEN Is a Better Game-State Boundary Than a Thread

A common mistake in threaded applications is to associate state too strongly with the thread currently executing.

A thread is only an execution context.

The chess game itself has a longer lifetime.

A useful game object needs to know things such as:

in progress or finished
white player
black player
current / final board state
whose turn is next

The board state can be represented using FEN (Forsyth-Edwards Notation).

This creates a useful separation:

Client
    = communication endpoint

Thread
    = code currently handling the endpoint

Game
    = shared application state

FEN
    = serializable chess position

For a human-vs-human game, two client threads can point at the same Game.

Neither thread is the game.

That lesson generalizes well beyond chess.

In concurrent servers, long-lived domain state should usually be represented explicitly rather than hidden inside thread-local control flow.

Lesson 7 - The Engine Can Be Reconstructed from State

Because the server stores the board as FEN, the single Stockfish instance can be switched between games.

Before asking the engine a question, the server can reconstruct the relevant position:

position fen <current FEN>

and then issue a query.

This is what makes sharing one engine practical.

The engine is not trusted as the only copy of the application state.

Instead:

server game state
      ↓
reconstruct Stockfish context
      ↓
ask question
      ↓
parse response
      ↓
update server game state

That architecture is much safer than allowing the child process to become an undocumented global state store.

It also resembles how stateless backend services are designed: send enough context with each transaction that the service can answer correctly.

Lesson 8 - Move Validation Is a Pipeline, Not a Boolean Function

A move such as:

e2e4

looks like it should produce:

valid / invalid

But the full server operation is richer.

A useful conceptual sequence is:

1. load the current FEN
2. apply the proposed move in the engine context
3. inspect the resulting board
4. determine whether the state changed
5. count legal replies
6. determine check / checkmate / stalemate
7. if playing the computer, request its best response
8. update FEN
9. notify the relevant client or clients

The UCI interface gives several tools for different parts of that process.

`position`

Defines the board state and optionally applies a candidate move.

`d`

Returns diagnostic board information, including state that can be used to recover the current FEN and detect check conditions.

`go perft 1`

Enumerates legal moves from the current position.

The number of legal replies matters when distinguishing:

check
checkmate
stalemate

`go movetime ... depth ...`

Searches for a best move, which can be used for hints or the computer opponent.

This part taught me that "validation" in a real application often crosses several subsystems.

It is not necessarily one function call.

Lesson 9 - Matchmaking Is a Shared-State Problem

Computer games are comparatively easy because one client owns one game.

Human matchmaking introduces a waiting pool.

A player can request:

white
black
either

The server has to find a compatible waiting client and create one shared game.

This means matchmaking requires a data structure that exists outside any single client thread.

Conceptually:

Client A asks for white
    ↓
search waiting pool
    ↓
compatible black/either player?
    ↓
yes -> create game and notify both
no  -> record Client A as waiting

The subtle part is that another client thread may modify the same pool at the same time.

So matchmaking is simultaneously:

application logic
+
concurrency control

I found this to be a good example of why race conditions are often really domain-state races, not just low-level memory races.

Lesson 10 - Disconnects Are Part of the Game Protocol

A socket closing is a transport event.

In a multiplayer game, it also has application meaning.

If one human player disconnects during a game, the other player needs to be told that the game is over.

So cleanup is not simply:

close(fd);
return;

The server may need to:

mark the game finished
notify the opponent
remove the client from matchmaking
release client resources
close the socket
terminate only that handler thread

This is another systems lesson that I found useful:

Resource cleanup and application-state cleanup are not always the same thing.

Closing the file descriptor handles the operating-system resource.

It does not automatically repair the application state that referenced that connection.

Lesson 11 - SIGPIPE Is a Networking Design Issue, Not an Edge Case

Writing to a closed pipe or socket can generate SIGPIPE.

If the default action is allowed to terminate the process, one disconnected client could accidentally kill the whole server.

Similarly, failure of the Stockfish pipe means something very different from failure of one client connection.

The failure policy should reflect the ownership boundary:

client socket failure
    -> terminate one client session
    -> server continues

Stockfish process failure
    -> shared engine unavailable
    -> all games lose engine service
    -> notify clients and terminate server

This is a clean example of failure domains.

The scope of recovery should match the scope of the failed resource.

Lesson 12 - Blocking Is Good When There Is Nothing to Do

Concurrent programs sometimes become complicated because developers try too hard to make everything continuously active.

A server thread waiting for work should often simply block.

Examples include:

accept()
read()
fgets()
getline()

A blocked thread consumes almost no CPU while waiting for an event.

The bad alternative is:

check socket
nothing there
check again
check again
sleep a little
check again

Busy waiting adds latency, wastes CPU, and makes the server harder to reason about.

This project reinforced an important Unix programming habit:

If progress depends on external input, block on the object that will deliver that input.

A Data Model I Would Use

If I were structuring the project again, I would make the major domain objects explicit.

Client

socket / FILE streams
selected game mode
requested colour
current Game pointer
connection state

Game

white client or computer
black client or computer
FEN
in-progress flag
finished state

Server

listener
client collection
waiting-player collection
engine connection
engine mutex
shared-state mutexes

Engine

child PID
write stream
read stream
transaction lock

The exact C structures can vary.

What matters is that ownership is visible from the model.

The Architecture I Would Prefer Today

I would still keep the overall thread-per-client model because it matches the scale of the problem well.

But I would make a few design rules explicit.

Keep socket parsing outside game logic

A function that updates a chess game should not also be responsible for splitting TCP lines.

Keep UCI parsing behind an engine API

The rest of the server should ask questions such as:

is this move valid?
what is the resulting FEN?
what are the legal moves?
what is the best move?
is the side in check?

rather than manually scanning Stockfish output everywhere.

Keep matchmaking operations atomic

Search + remove + create-game should be one protected state transition.

Keep lock scope understandable

The engine lock may need to cover a complete UCI transaction.

A game-state lock should not be held while waiting unnecessarily on slow I/O unless the consistency requirement demands it.

Treat messages to human opponents as cross-thread communication

One client handler may need to send a notification to another client's socket.

That should be an intentional capability of the data model, not an accidental global variable.

What I Would Improve in a Second Version

1. Add a dedicated engine worker thread

Instead of allowing client threads to directly acquire the Stockfish lock, I would consider giving the engine its own request queue.

The architecture becomes:

client threads
    ↓
engine-request queue
    ↓
single engine worker
    ↓
Stockfish

This serializes access naturally and makes the engine an active service rather than a locked resource.

2. Use typed internal requests

The network protocol is text.

The internal server representation does not need to be.

I would parse incoming messages immediately into structured requests such as:

START_GAME
BOARD_REQUEST
HINT_BEST
HINT_ALL
MOVE
RESIGN

That reduces repeated string handling inside domain logic.

3. Centralize game transitions

I would place all game lifecycle changes behind a small API:

game_start()
game_apply_move()
game_resign()
game_disconnect()
game_finish()

That makes it harder for two different request handlers to update state inconsistently.

4. Add stronger runtime instrumentation

I would measure:

connected clients
waiting players
active games
engine request latency
commands per client
lock wait time

Concurrency problems are much easier to diagnose when the program can explain what it is doing.

5. Test the server independently from the official client

Because the protocol is text based, I would use scripted raw TCP tests for:

malformed commands
rapid reconnects
two clients moving at nearly the same time
disconnect during a game
engine failure
human colour matching

That kind of testing is more effective than relying only on manual gameplay.

Final Thoughts

This project looked like a chess application, but most of the difficult reasoning had nothing to do with chess strategy.

The real questions were:

Who owns the board state?
How do several client threads share one engine?
How should two human clients be paired?
What must be protected by synchronization?
Which failures affect one session and which affect the whole service?
How do I preserve state when the executing thread changes?
Where should protocol parsing stop and domain logic begin?

Those questions appear in many real systems.

A database server, build service, multiplayer game, hardware-control daemon, or model-serving backend can all have the same underlying shape:

many clients
    ↓
concurrent request handling
    ↓
shared domain state
    ↓
serialized access to a limited resource

The most useful lesson I kept from the project is:

Concurrency becomes manageable when state ownership is explicit and communication boundaries are designed before the threads are added.

The threads themselves are not the architecture.

The architecture is the set of rules that determines how those threads are allowed to interact.

Building a Real-Time Rhythm Game on STM32: Timing, DMA, LEDs, and GUI Integration

GuanHua Yu — Thu, 20 Aug 2026 00:00:00 GMT

Building a Real-Time Rhythm Game on STM32: Timing, DMA, LEDs, and GUI Integration

A rhythm game is a surprisingly good real-time systems project.

On the surface, the idea is simple: play a song, light up the correct lane, detect a button press, and decide whether the player was early, late, or on time. Once everything runs on the same microcontroller, however, the problem becomes much more interesting. Audio must remain continuous, LEDs must update without flicker, button input must be timestamped accurately, files must be read from storage, and the user interface still has to feel responsive.

That was the main engineering challenge behind tpmania, a mini arcade rhythm game that our team built around an STM32-based embedded platform. The system combined a 16x4 addressable LED matrix, four illuminated arcade buttons, an OLED interface, microSD-based song and sequence storage, USB configuration, line-level audio, and a custom PCB.

My main work was on the firmware and the PC-side configuration GUI. I implemented the LED-matrix frame pipeline and colour mapping, beat and half-beat progression, button LED cueing, scoring windows and combo logic, sequence parsing, microSD file management, OLED overlays, and the PyQt-based host interface. More importantly, I had to make all of these parts coexist without destroying the timing behaviour of the game.

An intermediate hardware setup used to test the OLED menu, illuminated buttons, and LED-matrix timing together.

The System Was Really Several Real-Time Pipelines

I found it useful to stop thinking about the project as "one program" and instead think about it as several pipelines sharing one MCU.

flowchart LR
    SD[microSD<br/>.tsq + .wav] --> Parser[Sequence / File Parser]
    Parser --> Beat[Beat Scheduler]
    Beat --> LED[16x4 LED Matrix]
    Beat --> Score[Scoring Engine]
    BTN[Arcade Buttons] --> Score

    SD --> Audio[Audio Streaming]
    Audio --> DAC[PCM5102A / Line Out]

    OLED[OLED Menu] <--> Control[UI / Game State]
    Control --> Beat
    Control --> Audio

    GUI[PyQt GUI] <--> USB[USB CDC]
    USB <--> Control

The game only feels correct if these pipelines agree on time.

The LED matrix can be visually perfect and still feel wrong if it is a few tens of milliseconds away from the music. The button interrupt can be fast and still produce unfair scoring if it is compared against the wrong reference timestamp. A GUI can be responsive and still cause problems if configuration transfers block the embedded side at the wrong moment.

That changed the way I approached the firmware: timing was not a feature added near the end; it was part of the architecture.

Lesson 1 - Represent Musical Time Explicitly

The basic timing relationship is simple:

$$ T_{\text{beat}} = \frac{60}{\mathrm{BPM}} $$

and for a half-beat event:

$$ T_{\text{half}} = \frac{30}{\mathrm{BPM}} $$

But a working game needs more than a beat period. It needs a consistent definition of where each expected event occurs, how long the hit window lasts, and how input timestamps are compared against those events.

My scoring logic used configurable timing windows around the expected hit time. Conceptually:

             early                        late
               <---------------------------->
------ MISS ------ GOOD ---- PERFECT ---- GOOD ------ MISS ------
                          expected hit

Instead of treating the tolerances as unrelated fixed numbers, I tied them to the beat period. This made the scoring behaviour much more consistent when moving between slower and faster songs.

A simplified model is:

$$ W_i = \alpha_i T_{\text{beat}} $$

where $W_i$ is a timing window and $\alpha_i$ is a configurable tolerance ratio.

The embedded scheduler compares the button timestamp against the expected hit time:

$$ e = t_{\text{press}} - t_{\text{expected}} $$

and classifies the result based on $|e|$.

That may sound obvious, but this model became important once half-beat sequences were introduced. The initial project plan assumed single-beat events. Supporting half-beat content later forced changes across the sequence parser, the game state machine, the GUI, and the on-device interface.

:::important[One timing change can propagate through the whole stack] Changing the musical time model is not only a firmware change. It affects the file format, parser, visualisation, scoring rules, GUI configuration, and validation data. :::

Lesson 2 - Offload Repetitive Timing Work Whenever Possible

The LED matrix used addressable LEDs, which are convenient but timing-sensitive. Updating them directly from blocking code would consume too much CPU time and could interfere with the rest of the game.

The solution was to use a DMA-driven LED pipeline so that once the frame data had been prepared, hardware could handle much of the transfer while the CPU continued with game logic.

Conceptually, the frame path looked like this:

Game state
   ↓
Lane / beat mapping
   ↓
RGB frame buffer
   ↓
PWM/serial waveform buffer
   ↓
DMA transfer
   ↓
WS2812 LED matrix

The important lesson for me was not simply "DMA is fast."

The real advantage is that DMA makes execution more predictable. Instead of a large CPU loop competing with input handling and display logic, the CPU prepares data and then lets the peripheral move it.

This same principle appears throughout embedded systems:

use DMA for repetitive data movement;
let timers generate timing-critical events;
use peripherals for waveform generation;
keep interrupts short;
let the main application deal with state and policy.

The result is not only higher performance. It is a system that is easier to reason about.

Lesson 3 - Audio Problems Often Reveal Scheduling Problems

One of the most memorable integration issues was distorted audio during simultaneous OLED and LED activity.

The audio pipeline streamed 16-bit PCM data from microSD storage, transferred samples over I2S/SAI to a PCM5102A DAC, and used a ping-pong buffer so one half could be played while the other half was refilled.

The project used a double-buffered streaming pipeline so file access and playback could overlap.

The general pattern is:

sequenceDiagram
    participant SD as microSD
    participant CPU as CPU
    participant B0 as Buffer Half A
    participant B1 as Buffer Half B
    participant DMA as DMA / SAI
    participant DAC as PCM5102A

    CPU->>SD: Read next PCM block
    SD-->>CPU: Samples
    CPU->>B0: Fill A
    DMA->>B0: Stream A
    DMA->>DAC: I2S samples
    CPU->>B1: Fill B
    DMA->>B1: Stream B
    CPU->>B0: Refill A

The architecture is sound, but the system can still fail if some unrelated interrupt blocks the CPU for too long.

During integration, OLED and LED-related work could delay the audio path enough to produce audible distortion and pops. The oscilloscope became more useful than reading code because the failure was fundamentally temporal.

The audio path exposed scheduling and interrupt-latency problems that were difficult to see from source code alone.

This was a strong reminder that peripherals do not only compete for pins and buses. They also compete for:

CPU time;
interrupt latency;
memory bandwidth;
bus access;
buffer refill windows.

After this project, I became much more careful about putting expensive work inside interrupts. An interrupt should usually capture an event, update minimal state, and leave heavier processing to another execution context.

:::tip[Debug the timing, not just the function] When a subsystem works alone but fails during integration, check execution time, ISR duration, bus contention, and buffer deadlines before assuming the peripheral driver itself is wrong. :::

Lesson 4 - A Rhythm Game Needs a Content Pipeline, Not Just Firmware

Another part I underestimated was content management.

The game did not only need a .wav file. It also needed a sequence describing the timing and lane information used by the LED matrix and scoring logic. This meant that song data became a small data pipeline:

Song metadata
      +
Audio (.wav)
      +
Sequence (.tsq)
      ↓
microSD
      ↓
Embedded parser
      ↓
Game scheduler

The parser had to support both normal beats and half-beats, while the GUI needed to upload, delete, and manage the corresponding files.

This is where the project started to feel less like a microcontroller exercise and more like a complete product.

The microSD interface and file system were now part of the user experience. File naming, metadata consistency, parsing errors, and missing assets were no longer "storage problems" - they directly affected whether a song could be played.

I learned to treat data formats as interfaces in the same way I treat UART or SPI.

A sequence format should answer questions such as:

What is the version?
How is BPM represented?
Are timestamps absolute or beat-relative?
How are half-beats encoded?
What happens if a field is missing?
Can old firmware reject a newer sequence safely?

If I rebuilt the format today, I would introduce explicit versioning and stronger validation much earlier.

Lesson 5 - The PC GUI Was Part of the Embedded System

I also built a cross-platform configuration GUI in Python with PyQt.

It communicated with the embedded system over USB CDC and provided controls for timing-window configuration, general settings, device status, and microSD content management.

The host GUI exposed scoring tolerances and device configuration without requiring firmware recompilation.

The timing page was especially useful because it converted what would otherwise be compile-time constants into tunable parameters.

That made testing much faster.

Instead of:

change constant
→ rebuild firmware
→ flash MCU
→ replay song

I could do:

adjust GUI
→ send configuration
→ replay song

This matters in systems where the "correct" value is partly determined by human perception. A mathematically symmetric timing window may not necessarily feel fair when physical button latency, display delay, and audio latency are included.

The GUI also handled the music library on the storage device.

The GUI provided a host-side workflow for managing game assets and synchronising them with the embedded device.

One design choice I liked was keeping the host GUI conceptually similar to the on-device menu. Users should not have to learn two completely different mental models for the same settings.

This project made me appreciate that PC-side tooling is often an important part of embedded engineering. A good configuration and diagnostic interface can reduce firmware complexity, accelerate testing, and make hardware much easier to use.

Lesson 6 - Hardware-Software Co-Design Starts Before the PCB Is Finished

Although my main responsibility was firmware and GUI development, the custom PCB directly influenced software decisions.

The final hardware included the STM32 microcontroller, microSD interface, OLED connection, button connectors, LED-matrix connection, programming interface, test points, and power-related circuitry.

The schematic shows how the MCU, storage, display, buttons, LED matrix, test headers, and supporting hardware were organised.

The PCB artwork made the interfaces physical.

The custom PCB turned firmware assumptions about pins, connectors, power rails, and peripherals into fixed hardware constraints.

This is where hardware-software co-design becomes very concrete.

A firmware decision such as "I will use this timer channel for the LED output" affects PCB routing and pin assignment. A hardware decision such as "this connector is on this pin" may determine which peripheral instance is available in firmware.

I learned to review pin assignments, peripheral alternate functions, and timing-critical signals before layout is finalised. Waiting until the board arrives is too late to discover that two features depend on the same peripheral resource.

Validation: Real-Time Performance Has to Be Measured

The final system was tested across different songs and BPM values. According to our project validation, the final build maintained continuous playback without buffer underruns and achieved less than 2 ms latency between visual and audio events.

That result mattered because a rhythm game is unusually sensitive to timing errors.

For many applications, a few tens of milliseconds might be invisible. In a rhythm game, they can change whether the interaction feels responsive.

I now think of validation in three layers:

Layer	Example question
Functional	Did the correct lane light up?
Temporal	Did it light up at the correct time?
Perceptual	Did the game feel synchronised to the player?

Passing the first layer is not enough for a real-time interactive system.

What I Would Change in a Second Version

The prototype worked, but there are several things I would redesign if I started again.

1. Introduce an RTOS once the task graph becomes large

The project could be managed with a structured scheduler, timers, callbacks, and carefully controlled tasks. As the number of asynchronous activities increases, however, an RTOS such as FreeRTOS or Zephyr would make ownership and task isolation clearer.

I would separate at least:

Audio task
Game scheduler
Input task
LED rendering
Display/UI
Storage
USB/configuration

The goal would not be to "use an RTOS because it is more advanced." The goal would be to make deadlines and priorities explicit.

2. Build automated timing tests

Reference event timestamps were already useful for validation. I would extend that into an automated test harness that could:

load a known sequence;
inject synthetic button events;
verify scoring classifications;
sweep across BPM values;
detect timing regressions.

3. Define a stricter Git workflow

Multiple software environments created avoidable merge and synchronisation problems. A clearer branching strategy and automated checks would reduce integration risk.

4. Add protocol and file-format versioning

Both the USB configuration protocol and .tsq files should have explicit versions so that incompatible firmware and tools fail safely rather than behaving unpredictably.

5. Instrument performance from the beginning

I would reserve debug GPIOs and lightweight timing counters for:

ISR duration;
frame-update time;
buffer-refill time;
input-to-score latency;
audio deadline misses.

Instrumentation is much cheaper when designed in early.

Final Thoughts

tpmania changed how I think about real-time embedded design.

Before the project, I associated real-time systems mainly with fast interrupts and precise timers. After building an interactive system where audio, LEDs, storage, input, and GUI control all had to work simultaneously, I realised that real-time engineering is mostly about controlling interference between otherwise-correct subsystems.

The most important questions became:

Who owns this timing deadline?
Can this operation block?
What happens if the SD card is slow?
How long can this interrupt run?
Does this peripheral need DMA?
Which data is shared between tasks?
What happens when two features are active at the same time?

A feature can work perfectly in isolation and still fail at the system level.

That is probably the biggest lesson I took from the project:

A real-time embedded system is not a collection of fast components. It is a collection of components whose timing relationships are deliberately designed.

For me, that shift - from writing peripheral code to designing timing relationships - was the most valuable part of building the game.

代码块示例

GuanHua Yu — Fri, 03 Jan 2025 00:00:00 GMT

在这里，我们将探索如何使用 Expressive Code 展示代码块。提供的示例基于官方文档，您可以参考以获取更多详细信息。

表达性代码

语法高亮

常规语法高亮

console.log('此代码有语法高亮!')

渲染 ANSI 转义序列

ANSI colors:
- Regular: [31mRed[0m [32mGreen[0m [33mYellow[0m [34mBlue[0m [35mMagenta[0m [36mCyan[0m
- Bold:    [1;31mRed[0m [1;32mGreen[0m [1;33mYellow[0m [1;34mBlue[0m [1;35mMagenta[0m [1;36mCyan[0m
- Dimmed:  [2;31mRed[0m [2;32mGreen[0m [2;33mYellow[0m [2;34mBlue[0m [2;35mMagenta[0m [2;36mCyan[0m

256 colors (showing colors 160-177):
[38;5;160m160 [38;5;161m161 [38;5;162m162 [38;5;163m163 [38;5;164m164 [38;5;165m165[0m
[38;5;166m166 [38;5;167m167 [38;5;168m168 [38;5;169m169 [38;5;170m170 [38;5;171m171[0m
[38;5;172m172 [38;5;173m173 [38;5;174m174 [38;5;175m175 [38;5;176m176 [38;5;177m177[0m

Full RGB colors:
[38;2;34;139;34mForestGreen - RGB(34, 139, 34)[0m

Text formatting: [1mBold[0m [2mDimmed[0m [3mItalic[0m [4mUnderline[0m

编辑器和终端框架

代码编辑器框架

console.log('标题属性示例')

<!-- src/content/index.html -->
<div>文件名注释示例</div>

终端框架

echo "此终端框架没有标题"

Write-Output "这个有标题!"

覆盖框架类型

echo "看，没有框架!"

# 如果不覆盖，这将是一个终端框架
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail

文本和行标记

标记整行和行范围

// 第1行 - 通过行号定位
// 第2行
// 第3行
// 第4行 - 通过行号定位
// 第5行
// 第6行
// 第7行 - 通过范围 "7-8" 定位
// 第8行 - 通过范围 "7-8" 定位

选择行标记类型 (mark, ins, del)

function demo() {
  console.log('此行标记为已删除')
  // 此行和下一行标记为已插入
  console.log('这是第二个插入行')

  return '此行使用中性默认标记类型'
}

为行标记添加标签

// labeled-line-markers.jsx
<button
  role="button"
  {...props}
  value={value}
  className={buttonClassName}
  disabled={disabled}
  active={active}
>
  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

在单独行上添加长标签

// labeled-line-markers.jsx
<button
  role="button"
  {...props}

  value={value}
  className={buttonClassName}

  disabled={disabled}
  active={active}
>

  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

使用类似 diff 的语法

+此行将标记为已插入
-此行将标记为已删除
这是常规行

--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+this is an actual diff file
-all contents will remain unmodified
 no whitespace will be removed either

结合语法高亮和类似 diff 的语法

  function thisIsJavaScript() {
    // 整个块都会以 JavaScript 高亮显示，
    // 并且我们仍然可以为其添加 diff 标记！
-   console.log('要删除的旧代码')
+   console.log('新的闪亮代码！')
  }

标记行内的单独文本

function demo() {
  // 标记行内的任何给定文本
  return '支持给定文本的多个匹配项';
}

正则表达式

console.log('单词 yes 和 yep 将被标记。')

转义正斜杠

echo "Test" > /home/test.txt

选择内联标记类型 (mark, ins, del)

function demo() {
  console.log('这些是插入和删除的标记类型');
  // return 语句使用默认标记类型
  return true;
}

自动换行

为每个块配置自动换行

// 启用换行的示例
function getLongString() {
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
}

// wrap=false 的示例
function getLongString() {
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
}

配置换行的缩进

// preserveIndent 示例（默认启用）
function getLongString() {
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
}

// preserveIndent=false 的示例
function getLongString() {
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
}

可折叠部分

// 所有这些样板设置代码将被折叠
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// 这部分代码默认可见
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // 您可以有多个折叠部分
  const a = 1
  const b = 2
  const c = a + b

  // 这将保持可见
  console.log(`计算结果: ${a} + ${b} = ${c}`)
  return c
}

// 直到块末尾的所有代码将再次被折叠
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: '示例样板代码结束' })

行号

为每个块显示行号

// 此代码块将显示行号
console.log('来自第2行的问候!')
console.log('我在第3行')

// 此块禁用行号
console.log('你好?')
console.log('抱歉，你知道我在第几行吗?')

更改起始行号

console.log('来自第5行的问候!')
console.log('我在第6行')

KaTeX 数学公式示例

GuanHua Yu — Thu, 02 Jan 2025 00:00:00 GMT

本文展示了 Firefly 主题对 KaTeX 数学公式的渲染支持。

行内公式 (Inline)

行内公式使用单个 $ 符号包裹。

例如：欧拉公式 $e^{i\pi} + 1 = 0$ 是数学中最优美的公式之一。

质能方程 $E = mc^2$ 也是家喻户晓。

块级公式 (Block)

块级公式使用两个 $$ 符号包裹，会居中显示。

$$ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} $$

$$ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$

复杂示例

矩阵 (Matrices)

$$ \begin{pmatrix} a & b \ c & d \end{pmatrix} \begin{pmatrix} \alpha & \beta \ \gamma & \delta \end{pmatrix} = \begin{pmatrix} a\alpha + b\gamma & a\beta + b\delta \ c\alpha + d\gamma & c\beta + d\delta \end{pmatrix} $$

极限与求和 (Limits and Sums)

$$ \sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6} $$

$$ \lim_{x \to 0} \frac{\sin x}{x} = 1 $$

麦克斯韦方程组 (Maxwell's Equations)

$$ \begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \ \nabla \cdot \mathbf{B} &= 0 \ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \ \nabla \times \mathbf{B} &= \mu_0\mathbf{J} + \mu_0\varepsilon_0\frac{\partial \mathbf{E}}{\partial t} \end{aligned} $$

化学方程式 (Chemical Equations)

$$ \ce{CH4 + 2O2 -> CO2 + 2H2O} $$

符号	代码	渲染结果
Alpha	`\alpha`	$\alpha$
Beta	`\beta`	$\beta$
Gamma	`\Gamma`	$\Gamma$
Pi	`\pi`	$\pi$
Infinity	`\infty`	$\infty$
Right Arrow	`\rightarrow`	$\rightarrow$
Partial	`\partial`	$\partial$

Markdown Mermaid 图表

GuanHua Yu — Wed, 01 Jan 2025 00:00:00 GMT

Markdown 中 Mermaid 图表完整指南

本文演示如何在 Markdown 文档中使用 Mermaid 创建各种复杂图表，包括流程图、时序图、甘特图、类图和状态图。

流程图示例

流程图非常适合表示流程或算法步骤。

graph TD
    A[开始] --> B{条件检查}
    B -->|是| C[处理步骤 1]
    B -->|否| D[处理步骤 2]
    C --> E[子过程]
    D --> E
    subgraph E [子过程详情]
        E1[子步骤 1] --> E2[子步骤 2]
        E2 --> E3[子步骤 3]
    end
    E --> F{另一个决策}
    F -->|选项 1| G[结果 1]
    F -->|选项 2| H[结果 2]
    F -->|选项 3| I[结果 3]
    G --> J[结束]
    H --> J
    I --> J

时序图示例

时序图显示对象之间随时间的交互。

sequenceDiagram
    participant User as 用户
    participant WebApp as 网页应用
    participant Server as 服务器
    participant Database as 数据库

    User->>WebApp: 提交登录请求
    WebApp->>Server: 发送认证请求
    Server->>Database: 查询用户凭据
    Database-->>Server: 返回用户数据
    Server-->>WebApp: 返回认证结果
    
    alt 认证成功
        WebApp->>User: 显示欢迎页面
        WebApp->>Server: 请求用户数据
        Server->>Database: 获取用户偏好
        Database-->>Server: 返回偏好设置
        Server-->>WebApp: 返回用户数据
        WebApp->>User: 加载个性化界面
    else 认证失败
        WebApp->>User: 显示错误消息
        WebApp->>User: 提示重新输入
    end

甘特图示例

甘特图非常适合显示项目进度和时间线。

gantt
    title 网站开发项目时间线
    dateFormat  YYYY-MM-DD
    axisFormat  %m/%d
    
    section 设计阶段
    需求分析      :a1, 2023-10-01, 7d
    UI设计                 :a2, after a1, 10d
    原型创建        :a3, after a2, 5d
    
    section 开发阶段
    前端开发      :b1, 2023-10-20, 15d
    后端开发       :b2, after a2, 18d
    数据库设计           :b3, after a1, 12d
    
    section 测试阶段
    单元测试              :c1, after b1, 8d
    集成测试       :c2, after b2, 10d
    用户验收测试   :c3, after c2, 7d
    
    section 部署
    生产环境部署     :d1, after c3, 3d
    发布                    :milestone, after d1, 0d

类图示例

类图显示系统的静态结构，包括类、属性、方法及其关系。

classDiagram
    class User {
        +String username
        +String password
        +String email
        +Boolean active
        +login()
        +logout()
        +updateProfile()
    }
    
    class Article {
        +String title
        +String content
        +Date publishDate
        +Boolean published
        +publish()
        +edit()
        +delete()
    }
    
    class Comment {
        +String content
        +Date commentDate
        +addComment()
        +deleteComment()
    }
    
    class Category {
        +String name
        +String description
        +addArticle()
        +removeArticle()
    }
    
    User "1" -- "*" Article : 写作
    User "1" -- "*" Comment : 发表
    Article "1" -- "*" Comment : 拥有
    Article "1" -- "*" Category : 属于

状态图示例

状态图显示对象在其生命周期中经历的状态序列。

stateDiagram-v2
    [*] --> 草稿
    
    草稿 --> 审核中 : 提交
    审核中 --> 草稿 : 拒绝
    审核中 --> 已批准 : 批准
    已批准 --> 已发布 : 发布
    已发布 --> 已归档 : 归档
    已发布 --> 草稿 : 撤回
    
    state 已发布 {
        [*] --> 活跃
        活跃 --> 隐藏 : 临时隐藏
        隐藏 --> 活跃 : 恢复
        活跃 --> [*]
        隐藏 --> [*]
    }
    
    已归档 --> [*]

饼图示例

饼图非常适合显示比例和百分比数据。

pie title 网站流量来源分析
    "搜索引擎" : 45.6
    "直接访问" : 30.1
    "社交媒体" : 15.3
    "推荐链接" : 6.4
    "其他来源" : 2.6

总结

Mermaid 是在 Markdown 文档中创建各种类型图表的强大工具。本文演示了如何使用流程图、时序图、甘特图、类图、状态图和饼图。这些图表可以帮助您更清晰地表达复杂的概念、流程和数据结构。

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。Mermaid 会自动将这些描述转换为美观的可视化图表。

尝试在您的下一篇技术博客文章或项目文档中使用 Mermaid 图表 - 它们将使您的内容更加专业且更易理解！

在文章中嵌入视频

GuanHua Yu — Wed, 01 Jan 2025 00:00:00 GMT

只需从 YouTube 或其他平台复制嵌入代码，然后将其粘贴到 markdown 文件中。

---
title: 在文章中嵌入视频
published: 2023-10-19
// ...
---

<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

YouTube

Bilibili

Markdown 扩展功能

GuanHua Yu — Wed, 01 Jan 2025 00:00:00 GMT

GitHub 仓库卡片

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

::github{repo="CuteLeaf/Firefly"}

使用代码 ::github{repo="CuteLeaf/Firefly"} 创建 GitHub 仓库卡片。

::github{repo="CuteLeaf/Firefly"}

提醒框

支持以下类型的提醒框：note tip important warning caution

:::note 突出显示用户应该考虑的信息，即使在快速浏览时也是如此。 :::

:::tip 可选信息，帮助用户更成功。 :::

:::important 用户成功所必需的关键信息。 :::

:::warning 由于潜在风险需要用户立即注意的关键内容。 :::

:::caution 行动的负面潜在后果。 :::

基本语法

:::note
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
:::

:::tip
可选信息，帮助用户更成功。
:::

自定义标题

可以自定义提醒框的标题。

:::note[我的自定义标题] 这是一个带有自定义标题的注释。 :::

:::note[我的自定义标题]
这是一个带有自定义标题的注释。
:::

GitHub 语法

[!TIP] 也支持 GitHub 语法。

> [!NOTE]
> 也支持 GitHub 语法。

> [!TIP]
> 也支持 GitHub 语法。

剧透

您可以为文本添加剧透。文本也支持 Markdown 语法。

内容 :spoiler[被隐藏了哈哈]！

内容 :spoiler[被隐藏了 **哈哈**]！

Markdown 教程

emn178 — Wed, 01 Jan 2025 00:00:00 GMT

这是一个展示如何编写 Markdown 文件的示例。本文档汇总了核心语法与常见扩展（GFM）。

块级元素
- 段落与换行
- 标题
- 引用
- 列表
- 代码块
- 分割线
- 表格
内联元素
- 链接
- 强调
- 行内代码
- 图片
- 删除线
杂项
- 自动链接
- 反斜杠转义
内联 HTML

块级元素

段落与换行

段落

HTML 标签：<p>

使用一个或多个空行分隔段落。（仅包含空格或制表符的行也视为空行。）

代码：

This will be
inline.

This is second paragraph.

预览：

This will be inline.

This is second paragraph.

换行

HTML 标签：<br />

在行末添加两个或更多空格来产生换行。

代码：

This will be not
inline.

预览：

This will be not
inline.

标题

Markdown 支持两种标题样式：Setext 与 atx。

Setext

HTML 标签：<h1>，<h2>

使用等号 (=) 表示 <h1>、使用短横线 (-) 表示 <h2>，数量不限，作为“下划线”。

代码：

This is an H1
=============
This is an H2
-------------

预览：

This is an H1

This is an H2

atx

HTML 标签：<h1>，<h2>，<h3>，<h4>，<h5>，<h6>

在行首使用 1-6 个井号 (#)，对应 <h1> 至 <h6>。

代码：

# This is an H1
## This is an H2
###### This is an H6

预览：

This is an H1

This is an H2

This is an H6

可选：你可以在行尾“闭合” atx 标题。末尾的井号数量不必与开头一致。

代码：

# This is an H1 #
## This is an H2 ##
### This is an H3 ######

预览：

This is an H1

This is an H2

This is an H3

引用

HTML 标签：<blockquote>

Markdown 使用邮件风格的 > 作为引用符号。若手动换行并在每行前加 >，显示效果最佳。

代码：

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown 允许“偷懒”：在一个硬换行段落中，只在第一行前加 > 即可。

代码：

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

引用可以嵌套（引用中的引用），通过增加 > 层级实现。

代码：

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

预览：

This is the first level of quoting.

This is nested blockquote.

Back to the first level.

引用内可包含其他 Markdown 元素，包括标题、列表与代码块。

代码：

> ## This is a header.
>
> 1.   This is the first list item.
> 2.   This is the second list item.
>
> Here's some example code:
>
>     return shell_exec("echo $input | $markdown_script");

预览：

This is a header.

This is the first list item.

This is the second list item.

Here's some example code:
return shell_exec("echo $input | $markdown_script");

列表

Markdown 支持有序（数字）与无序（圆点）列表。

无序列表

HTML 标签：<ul>

无序列表可使用 星号 (*)、加号 (+) 或 短横线 (-)。

代码：

*   Red
*   Green
*   Blue

预览：

Red
Green
Blue

等价于：

代码：

+   Red
+   Green
+   Blue

或者：

代码：

-   Red
-   Green
-   Blue

有序列表

HTML 标签：<ol>

有序列表使用数字加英文句点：

代码：

1.  Bird
2.  McHale
3.  Parish

预览：

Bird
McHale
Parish

注意：像下面这样可能会“意外触发”有序列表：

代码：

1986. What a great season.

预览：

What a great season.

你可以用反斜杠转义 (\) 句点：

代码：

1986\. What a great season.

预览：

1986. What a great season.

列表中的缩进内容

列表项里的引用

在列表项内放置引用，需要将 > 符号整体缩进：

代码：

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

预览：

A list item with a blockquote:

This is a blockquote inside a list item.

列表项里的代码块

在列表项内放置代码块，需要缩进两层——8 个空格或两个 Tab：

代码：

*   A list item with a code block:

        <code goes here>

预览：

A list item with a code block:
```
<code goes here>
```

嵌套列表

代码：

* A
  * A1
  * A2
* B
* C

预览：

A
- A1
- A2
B
C

代码块

HTML 标签：<pre>

将代码块中的每行缩进至少4 个空格或1 个制表符。

代码：

This is a normal paragraph:

    This is a code block.

预览：

This is a normal paragraph:

This is a code block.

代码块会一直持续，直到遇到未缩进的行（或文末）。

在代码块内，与号 (&) 和尖括号 (< >) 会自动转为 HTML 实体。

代码：

    <div class="footer">
        &copy; 2004 Foo Corporation
    </div>

预览：

<div class="footer">
    &copy; 2004 Foo Corporation
</div>

下文的“围栏代码块”和“语法高亮”属于扩展语法，你也可以用它们来书写代码块。

围栏代码块

使用成对的反引号围起来（如下所示），就不需要四空格缩进了。

代码：

Here's an example:

```
function test() {
  console.log("notice the blank line before this function?");
}
```

预览：

Here's an example:

function test() {
  console.log("notice the blank line before this function?");
}

语法高亮

在围栏代码块后添加可选的语言标识，即可启用语法高亮（参见支持语言列表）。

代码：

```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```

预览：

require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html

分割线（水平线）

HTML 标签：<hr /> 一行中放置三个或以上的短横线 (-)、星号 (*) 或下划线 (_)。符号之间允许有空格。

代码：

* * *
***
*****
- - -
---------------------------------------
___

预览：

表格

HTML 标签：<table>

这是扩展语法。

用竖线 (|) 分隔列，用短横线 (-) 分隔表头，使用冒号 (:) 指定对齐方式。

两侧的竖线 (|) 与对齐可选。用于表头分隔时，每列至少需要 3 个短横线。

代码：

| Left | Center | Right |
|:-----|:------:|------:|
|aaa   |bbb     |ccc    |
|ddd   |eee     |fff    |

 A | B
---|---
123|456


A |B
--|--
12|45

预览：

Left	Center	Right
aaa	bbb	ccc
ddd	eee	fff

A	B
123	456

A	B
12	45

内联元素

链接

HTML 标签：<a>

Markdown 支持两种链接样式：行内链接与引用式链接。

行内链接

行内链接格式：[文本](URL "标题")

标题可选。

代码：

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

预览：

This is an example inline link.

This link has no title attribute.

如果引用同一站点的本地资源，可以使用相对路径：

代码：

See my [About](/about/) page for details.

预览：

See my About page for details.

引用式链接

可以预定义链接引用。定义格式：[id]: URL "标题"

标题同样可选。引用时使用：[文本][id]

代码：

[id]: http://example.com/  "Optional Title Here"
This is [an example][id] reference-style link.

预览：

This is an example reference-style link.

说明：

方括号中包含链接标识（不区分大小写，可在左侧缩进最多三格空格）；
随后是冒号；
再跟一个或多个空格（或 tab）；
然后是链接 URL；
URL 可选地用尖括号包裹；
可选地跟随标题属性，用引号或圆括号包裹。

以下三种定义等价：

代码：

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)
[foo]: <http://example.com/>  "Optional Title Here"

如果使用空的方括号，则链接文本本身会作为名称。

代码：

[Google]: http://google.com/
[Google][]

预览：

Google

强调

HTML 标签：<em>，<strong>

Markdown 使用 星号 (*) 或 下划线 (_) 表示强调。一个分隔符对应 <em>；两个分隔符对应 <strong>。

代码：

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

预览：

single asterisks

single underscores

double asterisks

double underscores

但如果两侧有空格，则会被视作普通字符而非强调语法。

你可以使用反斜杠进行转义：

代码：

\*this text is surrounded by literal asterisks\*

预览：

*this text is surrounded by literal asterisks*

行内代码

HTML 标签：<code>

用反引号 (`) 包裹。

代码：

Use the `printf()` function.

预览：

Use the printf() function.

若行内代码中需要包含反引号字符，可使用多重反引号作为定界符：

代码：

``There is a literal backtick (`) here.``

预览：

There is a literal backtick (`) here.

行内代码两侧的定界符允许包含空格（开头一个、结尾一个），方便在代码起始或结尾放置反引号字符：

代码：

A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``

预览：

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

图片

HTML 标签：<img />

Markdown 的图片语法与链接类似，支持行内与引用两种方式。

行内图片

行内图片语法：![替代文本](URL "标题")

标题可选。

代码：

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

预览：

说明：

一个感叹号 !；
后接方括号，放置图片的替代文本；
再接圆括号，内含图片 URL/路径，及可选的标题（引号包裹）。

引用式图片

引用式图片语法：![替代文本][id]

代码：

[img id]: https://s2.loli.net/2024/08/20/5fszgXeOxmL3Wdv.webp  "Optional title attribute"
![Alt text][img id]

预览：

删除线

HTML 标签：<del>

这是扩展语法。

GFM 增加了删除线语法。

代码：

~~Mistaken text.~~

预览：

~~Mistaken text.~~

杂项

自动链接

Markdown 支持一种便捷写法来创建“自动链接”（URL 与邮箱地址）：只需用尖括号将其包住即可。

代码：

<http://example.com/>

<address@example.com>

预览：

http://example.com/

address@example.com

GFM 会自动识别标准 URL 并转换为链接。

代码：

https://github.com/emn178/markdown

预览：

https://github.com/emn178/markdown

反斜杠转义

Markdown 允许使用反斜杠来转义那些本用于 Markdown 语法的特殊字符，使其按字面显示。

代码：

\*literal asterisks\*

预览：

*literal asterisks*

以下字符可通过反斜杠转义以按字面量输出：

Code:

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

内联 HTML

对于 Markdown 语法未覆盖的标记，直接使用原生 HTML 即可。无需特别声明从 Markdown 切换到 HTML，直接写标签就行。

代码：

This is a regular paragraph.

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

This is another regular paragraph.

预览：

This is a regular paragraph.

This is another regular paragraph.

请注意：在块级 HTML 标签内不会处理 Markdown 语法。

与块级标签不同，在行内级标签内会处理 Markdown 语法。

代码：

<span>**Work**</span>

<div>
    **No Work**
</div>

预览：