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:

1
Wall
2
Target
3
Box
4
Player
5
Empty

But some cells contain overlapping meaning.

For example:

1
player + target
2
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.

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:

1
if (pixel_is_yellow(next_x, next_y)) {
2
    // wall
3
}

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:

1
if (is_wall(next_position)) {
2
    reject_move();
3
}
4
else if (has_box(next_position)) {
5
    try_push_box();
6
}
7
else {
8
    move_player();
9
}

Rendering happens afterwards.

Conceptually:

1
Game State
2
    ↓
3
render_led_matrix()
4
render_terminal()
5
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:

1
button right -> move right
2
terminal 'd' -> move right
3
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:

Every frontend should translate physical input into a common command.

For example:

1
typedef enum {
2
    MOVE_UP,
3
    MOVE_DOWN,
4
    MOVE_LEFT,
5
    MOVE_RIGHT
6
} direction_t;

Then:

1
handle_button_input();
2
handle_uart_input();
3
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
1. Empty cell        -> player moves
2
2. Target            -> player moves onto target
3
3. Wall              -> movement rejected
4
4. Box + free space  -> box moves, then player moves
5
5. Box + wall        -> movement rejected
6
6. Box + box         -> movement rejected
7
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.

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:

1
calculate destination
2
calculate box destination if needed
3
validate entire move
4
commit changes
5
render

rather than:

1
move player
2
discover collision
3
undo part of the move
4
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$:

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:

1
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:

1
turn_player_on();
2
_delay_ms(200);
3
turn_player_off();
4
_delay_ms(200);

makes the animation correct but the game unresponsive.

The better pattern is to compare timestamps:

1
if (now_ms - last_flash_ms >= FLASH_INTERVAL_MS) {
2
    player_visible = !player_visible;
3
    last_flash_ms = now_ms;
4
}

Now the main loop can continue processing:

1
buttons
2
UART
3
joystick
4
game logic
5
display
6
sound

between animation events.

The difference is fundamental:

1
Blocking timing:
2
do task -> wait -> continue
3

4
Non-blocking timing:
5
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.

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:

1
wall-clock time

and:

1
active gameplay time

One simple model is:

When pausing:

1
pause_start = now

When resuming:

1
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:

1. the 16x8 LED matrix;
2. a serial terminal view;
3. 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:

1
update_game_state();
2

3
render_led_matrix();
4
render_terminal();
5
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:

1
show tens
2
disable
3
show ones
4
disable
5
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:

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:

1
internal state

and:

1
display representation

Lesson 9 - Joystick Input Exposes Weak Movement Abstractions#

Adding a joystick changed the movement problem.

Cardinal movement is one step:

1
north
2
south
3
east
4
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:

1
east -> north

or:

1
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:

1
tone(440);
2
_delay_ms(100);
3
tone(660);
4
_delay_ms(100);

Now input handling stops for 200 ms.

A better sound engine keeps track of:

1
current tone
2
tone duration
3
sequence index
4
next update time
5
mute state

and advances the sequence from the normal event loop.

Conceptually:

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:

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:

1
03

but the real step count could be:

1
103

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.

1
SPI
2
UART
3
GPIO
4
ADC
5
timers
6
PWM

1
read_joystick_direction()
2
button_pressed()
3
display_board()
4
set_step_count()
5
play_sound()

1
positions
2
walls
3
boxes
4
targets
5
moves

1
START
2
PLAYING
3
PAUSED
4
GAME_OVER

What I Would Improve in a Second Version#

1
PLAYER_MOVED
2
MOVE_REJECTED
3
BOX_PUSHED
4
BOX_ON_TARGET
5
LEVEL_COMPLETE

1
player flashing
2
target animation
3
seven-segment multiplexing
4
sound sequencing
5
level-time refresh

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

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.