There's an old meme: if a device has a screen, it should run Doom. People have run it on fridges, ATMs, and pregnancy tests. Now it's Lilka's turn — a Ukrainian DIY console built on the ESP32-S3. Here's where to legally get the game, what a WAD is, and what runs — and what doesn't.

How to run Doom on Lilka 

You need two files on the SD card:

1. The firmware — grab doom.bin from the doom_port releases page.
2. The game — a WAD file (see below where to get one). It must go in the root of the SD card and must be named doom.wad (episode-based games: Doom 1, Freedoom Phase 1) or doom2.wad (Doom II, Plutonia, Freedoom Phase 2) — other names won't be recognized. One WAD at a time: the port loads the first doom*.wad it finds.

You can copy both files with a card reader or over Wi-Fi via Keira Web Manager. Then launch doom.bin from the Keira menu on your Lilka — and rip and tear.

WAD, IWAD, PWAD

The engine is just a "player". The actual game — levels, monsters, textures, sounds — lives in a single .wad file (Where's All the Data). An IWAD is a complete game; a PWAD is an add-on that only works on top of one. So "getting Doom" means getting an IWAD.

Where to get games legally

• Doom Shareware (doom1.wad) — the first episode, free since 1993

How to extract doom1.wad from the shareware archive. The official shareware release (doom19s.zip from /idgames) is a 1995 installer split for floppy disks, so you won't see the WAD file right away. The files DOOMS_19.1 and DOOMS_19.2 are two halves of a regular zip archive. Join them and unpack.

macOS / Linux (Terminal, in the folder with the files):

cat DOOMS_19.1 DOOMS_19.2 > dooms19.zip
unzip dooms19.zip

Windows (Command Prompt):

copy /b DOOMS_19.1+DOOMS_19.2 dooms19.zip

then unpack dooms19.zip with any archiver.

Among the extracted DOS files you'll find DOOM1.WAD (~4 MB) — that's the one we need. The rest (DOOM.EXE, SETUP.EXE, etc.) can be deleted. If you'd rather skip the hassle, the same WAD is available on the Internet Archive in plain form.

• Freedoom — a free community-made game on the Doom engine. Phase 1 is episode-based like Doom 1, Phase 2 is like Doom II.

• DOOM + DOOM II on GOG or Steam — four classic games in one package: Doom, Doom II, and Final Doom (TNT + Plutonia).

When you buy DOOM + DOOM II on GOG, you get a Windows installer (setup_doom_plus_doom_ii_...exe). The easiest way on Windows is to just install the game: the WADs will be in the installation folder, with the classic DOS versions in the dosdoom\base\ subfolder.

You can also skip the installation — the innoextract utility pulls files out of the installer like from a regular archive:

• Windows: download innoextract.exe (or winget install innoextract), then in Command Prompt, in the folder with the installer:

innoextract setup_doom_plus_doom_ii_....exe

• macOS / Linux: brew install innoextract (or use your package manager), then the same command.

The extracted folders will appear next to the installer — look for the WADs in dosdoom/base/: the original DOOM.WAD and DOOM2.WAD are there, with Plutonia and TNT in the neighboring subfolders.

Chex Quest (1996) is probably the strangest game ever built on the Doom engine: a shooter given away for free in Chex cereal boxes as a promo. Instead of demons — slimy alien Flemoids; instead of guns — "zorchers" that don't kill enemies but teleport them back home: not a drop of blood, it's a kids' game after all. Underneath, though, it's a full-fledged Doom — and a cult classic today. Legally free; runs on Lilka. Grab the WAD from the Internet Archive and rename it to doom.wad.

What to do when something won't start

Your most valuable diagnostic tool is the serial log. Connect Lilka to your computer via USB and open serial.huhn.me in Chrome: click Connect, pick Lilka's port, set the speed to 115200 — nothing to install.

 If you prefer a desktop app, the free CoolTerm (Mac/Win/Linux) does the same job; terminal fans can simply run screen /dev/tty.usbmodem* 115200 on macOS/Linux.

The log captures everything the engine is thinking during startup: how much memory it allocated, which WAD it found on the card, where it stumbled. Errors that never make it to Lilka's screen are fully visible here.

For example, I tried to trick the engine by renaming a Heretic WAD to doom.wad. It didn't fall for it — the engine checks the file's contents, not just the name, and politely replied in the log:

adding /sd/DOOM.wad
IWAD file with the doomgenericdoom binary.
This isn't going to work.
You probably want to use the doomgenericheretic binary.

"This isn't going to work, you want the heretic binary." Thirty years old, and still the politest error message around.

In place of a conclusion

The Doom engine is not one game — it's a whole world: it powered fantasy games with elves and wizards (Heretic, Hexen), a shooter-RPG with dialogues (Strife), a kids' game about cereal (Chex Quest), a Viking epic (REKKR) — and thousands of fan-made games and levels still being created today, thirty years on. The full list of IWAD games is on the Doom Wiki — grab one, experiment, and let Lilka show you what a 1993 engine can do. It runs Doom. And not only Doom.

Lilka is an open-source handheld console based on the ESP32, built by the Ukrainian maker community 🇺🇦. One of its nicest features is mJS support — which means programs for Lilka can be written in JavaScript, the same language that powers half of the modern web.

mJS is a tiny JavaScript engine from Cesanta, built specifically for microcontrollers. The syntax is familiar, but standard JS libraries (React, npm modules, and the like) aren't supported — only the basic language and Lilka's own APIs. For simple scripts, that's perfectly fine.

And the coolest part — no compilation, no reflashing. A script is just a .js file on the SD card: pick it in the menu and it runs. Edit the code, save, launch again — the whole cycle takes seconds ⚡ That's what makes Lilka such a great platform for tinkering and learning to code.

A quick note before we dive in: mJS support is a fairly fresh addition to KeiraOS, introduced in v2.6.5 and still actively being developed. Things mostly work, but you might run into the occasional rough edge — for example, an error 2message that pops up every time you exit a script. It's harmless and doesn't affect anything else, just close it and move on. New mJS features and fixes are landing release after release, so the experience keeps getting smoother 🚀

🐱 Cat App

Cat.js Let's walk through a simple program in the style of Bongo Cat — a kitty that smacks its paws on the table when you press buttons 🥁 Press B — the cat claps with its right paw. D — with the left. Both at once — a double slap, just like in the real meme. And if you press C — a quick blink with a muffled "thunk" from the buzzer 💭

The whole "secret" is four BMP images on the SD card: no.bmp (the calm cat), left.bmp, right.bmp, and both.bmp. We load them once at the start via resources.load_image(), and from there each frame we just decide which picture to draw on top based on the button state 🎨

The logic is so simple it fits into about a dozen lines: first we draw the base image (no), and then on top we overlay the "paw variant" — if the matching button is held. It's a classic layering trick: every frame starts from a clean base, and details get stacked on top ⚙️

One neat detail — buzzer.play(40, 100). 40 Hz is already near the edge of audibility, a deep low "thump". That's exactly why the paw slaps sound not like a beep but like a dull "tap-tap" — perfect for bongos 🔉

// cat.js — Cat with ears controlled by buttons
// Port of LUA/cat/cat.lua
// Required: no.bmp, left.bmp, right.bmp, both.bmp in the same directory

// Load images
let no = resources.load_image("no.bmp");
let left = resources.load_image("left.bmp");
let right = resources.load_image("right.bmp");
let both = resources.load_image("both.bmp");

let running = true;

while (running) {    let state = controller.get_state();
    // Play sound when ear buttons are just pressed    if (state.b.just_pressed || state.d.just_pressed) {        buzzer.play(40, 100);    }
    // Exit on A button    if (state.a.pressed) {        running = false;    }
    // Draw the appropriate image based on button state    display.draw_image(no, 0, 0);    if (state.d.pressed) {        display.draw_image(left, 0, 0);    }    if (state.b.pressed) {        display.draw_image(right, 0, 0);    }    if (state.b.pressed && state.d.pressed) {        display.draw_image(both, 0, 0);    }    if (state.c.pressed) {        util.sleep(0.1);        display.draw_image(both, 0, 0);        buzzer.play(40, 100);        display.queue_draw();        util.sleep(0.1);        display.draw_image(no, 0, 0);    }
    display.queue_draw();    util.sleep(0.016);
}

And the best thing about this example is that it's not really a program — it's a template. Swap the four BMP files for your own, and in 10 minutes you've got your own character: a dog sticking out its tongue; a robot blinking its LEDs; your own photo pulling faces on command 📸 The code structure doesn't change by a single line — just different pictures. That's exactly where mJS wins: no reflashing the device, no building a project. Drop new BMPs onto the SD card — and you're already running a new character ⚡

🌌 Starfield App

Starfield.js Let's recreate that classic "flying through space" effect — stars streaming past the camera, growing brighter as they get close, fading to tiny dots in the distance 🚀 A great example of how a 3D illusion can be built from very simple ingredients.

Each star lives in three numbers: sx, sy, and sz. The first two are its position on the screen, and sz is the distance from the camera — its depth. Every frame we subtract speed from sz, which means the star gets a bit closer. When sz reaches zero, the star has flown past the camera, so we send it back into the distance with fresh random coordinates and a maximum szagain ✨

The whole 3D illusion comes down to a single line of math:

px = sx * 256 / sz + w / 2

This is called perspective projection — the closer the star (smaller sz), the further from the center of the screen it ends up. That outward motion from the middle of the display is exactly what our eyes read as forward flight through space. The same trick scales size and brightness too: nearby stars become bright dots, distant ones fade to a single dim pixel. UP and DOWN change the speed live.

// starfield.js — Classic starfield effect
// Stars fly toward the camera. Press A to exit.

let w = display.width;
let h = display.height;
let numStars = 80;

// Initialize stars as arrays: [x, y, z]
let sx = [];
let sy = [];
let sz = [];

for (let i = 0; i < numStars; i++) {    sx[i] = math.random(-w, w);    sy[i] = math.random(-h, h);    sz[i] = math.random(1, w);
}

let speed = 8;
let running = true;

while (running) {    display.fill_screen(colors.black);    for (let i = 0; i < numStars; i++) {        sz[i] = sz[i] - speed;        if (sz[i] <= 0) {            sx[i] = math.random(-w, w);            sy[i] = math.random(-h, h);            sz[i] = w;        }        let px = math.round(sx[i] * 256 / sz[i] + w / 2);        let py = math.round(sy[i] * 256 / sz[i] + h / 2);        if (px >= 0 && px < w && py >= 0 && py < h) {            let brightness = math.round(255 - sz[i] * 255 / w);            brightness = math.clamp(brightness, 50, 255);            let color = display.color565(brightness, brightness, brightness);            let size = math.round(3 - sz[i] * 3 / w);            if (size < 1) {                size = 1;            }            if (size > 1) {                display.fill_circle(px, py, size, color);            } else {                display.draw_pixel(px, py, color);            }        }    }    display.set_cursor(5, h - 12);    display.set_text_color(colors.white);    display.print("A=exit  U/D=speed");    display.queue_draw();    let state = controller.get_state();    if (state.a.just_pressed) {        running = false;    }    if (state.up.pressed) {        speed = math.clamp(speed + 1, 1, 30);    }    if (state.down.pressed) {        speed = math.clamp(speed - 1, 1, 30);    }    util.sleep(0.016);
}

🔴 Bouncing Ball App

A red ball flies around the screen, bouncing off the walls, with a fiery trail behind it 🔥 A kind of "physics without physics" — the simplest example of how a single arithmetic rule, repeated 60 times a second, creates the feeling of living motion.

The whole logic boils down to two things. First — movement: every frame we add velocity to position (x = x + vx), and the ball shifts. The bigger the velocity, the more it leaps across the screen — no acceleration formulas, no mass, just two numbers vx and vy. Second — bouncing: when the ball touches a wall, we flip the sign of the corresponding velocity (vx = -vx). Was moving right — now moving left, and vice versa. This trick is the foundation of every game with flying projectiles, from Pong to Breakout.

The trail behind the ball is another simple trick: we draw two more circles slightly behind the main position (x - vx * 2 and x - vx * 4), with smaller radius and darker colors. The faster the ball flies, the longer and brighter the trail becomes, because vx * 4 turns into a bigger offset 💨

The D-pad changes velocity in real time: UP slows down vertical motion, DOWN speeds it up; LEFT and RIGHT do the same horizontally. You can accelerate the ball to a frantic pace, or almost freeze it mid-air, watching the trail collapse into a single dot.

// bouncing_ball.js — A ball bouncing around the screen
// Use D-pad to change ball speed. Press A to exit.

let w = display.width;
let h = display.height;
let r = 15;

let x = w / 2;
let y = h / 2;
let vx = 3;
let vy = 2;

let running = true;

while (running) {    // Update position    x = x + vx;    y = y + vy;
    // Bounce off walls    if (x - r < 0 || x + r > w) {        vx = -vx;        x = math.clamp(x, r, w - r);    }    if (y - r < 0 || y + r > h) {        vy = -vy;        y = math.clamp(y, r, h - r);    }
    // Draw    display.fill_screen(colors.black);    display.fill_circle(math.round(x), math.round(y), r, colors.red);
    // Trail effect: smaller circles behind    display.fill_circle(math.round(x - vx * 2), math.round(y - vy * 2), r - 4, display.color565(100, 0, 0));    display.fill_circle(math.round(x - vx * 4), math.round(y - vy * 4), r - 8, display.color565(50, 0, 0));
    // HUD    display.set_cursor(5, 15);    display.set_text_color(colors.white);    display.print("Bouncing Ball | A=exit");
    display.queue_draw();
    // Input    let state = controller.get_state();    if (state.a.just_pressed) {        running = false;    }    if (state.up.pressed) {        vy = vy - 0.2;    }    if (state.down.pressed) {        vy = vy + 0.2;    }    if (state.left.pressed) {        vx = vx - 0.2;    }    if (state.right.pressed) {        vx = vx + 0.2;    }
    util.sleep(0.016);
}

The same mechanic powers half the games ever made — Pong, Arkanoid, Breakout, even the classic DVD-logo screensaver waiting for that one perfect corner hit 📐 Swap the ball for anything else: a spaceship sprite, an apple, a tennis ball — and you get an entirely different game on the very same skeleton ⚡

🟠 Bouncing DVD Logo App

Replace the red ball with the legendary DVD logo, and you get that nostalgic 2000s screensaver everyone remembers 📺 The movement and bouncing logic stays exactly the same — but all the interesting stuff hides in working with the image itself.

🖼️ Loading images in mJS. You can add your own images to a Lilka program — photos, logos, game sprites. The code for it is minimal:

let dvd = resources.load_image("dvd-white.bmp", colors.black);
display.draw_image(dvd, x, y);

The dvd-white.bmp file should sit in the same SD-card folder as the .js script. Lilka resolves the relative path automatically.

🎨 BMP format, 24-bit. Lilka works with plain uncompressed BMP — 8 bits per channel for R, G, B. Not 1-bit black-and-white, not 32-bit with alpha — exactly 24-bit RGB. You can verify a file with sips -g all dvd-white.bmp: the output should show bitsPerSample: 8 and samplesPerPixel: 3.

✨ Transparency through color, not an alpha channel. BMP doesn't support transparency directly, so Lilka handles it differently: at load time you specify "this color shouldn't be drawn." The second argument of resources.load_image() is that transparencyColor. In the example above, the black background of the BMP becomes transparent and only the logo itself shows on screen. Pick a transparency color that doesn't appear in the image itself: black background for a white logo, white background for a black one.

📐 Optimal size. The Lilka display is 240×280 pixels. Rough guidelines: 32×32 for small objects, 64×64 for the main character of a game, 128×128 and up for large central elements. For the DVD logo with its 2:1 aspect ratio, 240×108 works beautifully.

🪄 ImageMagick is a universal command-line tool for image processing, available on macOS (brew install imagemagick), Linux (apt install imagemagick), and Windows. A single command can crop, invert, resize, and convert into the right format:

magick dvd.jpg -fuzz 10% -trim +repage -fill black -opaque white \       -resize 240x -type TrueColor BMP3:dvd-white.bmp

-trim strips the white margins around the logo, -opaque white replaces the white background with black (so transparency works), -resize 240x sets the width while preserving aspect ratio, and BMP3: guarantees the exact 24-bit BMP that Lilka expects 🎯

What changed in the code compared to Bouncing Ball:

Instead of a single radius r, there are now two variables — dvdW and dvdH — because the logo has different width and height. The wall bounce check is now computed separately for each axis: dvdW / 2 for the left and right walls, dvdH / 2 for top and bottom. The three fill_circle calls (the ball plus two trail circles) are replaced with a single display.draw_image() that draws the ready-made picture. And one small detail — draw_image takes coordinates of the top-left corner, not the center (unlike fill_circle), so we subtract dvdW / 2 and dvdH / 2 to keep the logo centered at point (x, y).

// dvd_bounce.js — DVD logo bouncing around the screen
// Use D-pad to change logo speed. Press A to exit.
// Required: dvd-white.bmp on the SD card (24-bit BMP, e.g. 240x108).

let w = display.width;
let h = display.height;

// Load DVD logo. Black is treated as transparent.
let dvd = resources.load_image("dvd-white.bmp", colors.black);
let dvdW = 240;
let dvdH = 108;

let x = w / 2;
let y = h / 2;
let vx = 3;
let vy = 2;

let running = true;

while (running) {    // Update position    x = x + vx;    y = y + vy;
    // Bounce off walls    if (x - dvdW / 2 < 0 || x + dvdW / 2 > w) {        vx = -vx;        x = math.clamp(x, dvdW / 2, w - dvdW / 2);    }    if (y - dvdH / 2 < 0 || y + dvdH / 2 > h) {        vy = -vy;        y = math.clamp(y, dvdH / 2, h - dvdH / 2);    }
    // Draw    display.fill_screen(display.color565(20, 20, 60));    display.draw_image(dvd, math.round(x - dvdW / 2), math.round(y - dvdH / 2));
    // HUD    display.set_cursor(5, 15);    display.set_text_color(colors.white);    display.print("DVD Bounce | A=exit");
    display.queue_draw();
    // Input    let state = controller.get_state();    if (state.a.just_pressed) {        running = false;    }    if (state.up.pressed) {        vy = vy - 0.2;    }    if (state.down.pressed) {        vy = vy + 0.2;    }    if (state.left.pressed) {        vx = vx - 0.2;    }    if (state.right.pressed) {        vx = vx + 0.2;    }
    util.sleep(0.016);
}

It's the very same template as cat.js — a simple skeleton you can drop any image into. Swap dvd-white.bmp for the logo of your favorite band, a photo of your pet, your friend's avatar — and in two minutes you've got a personal screensaver ⚡ And there's still that legendary moment to wait for: when the logo finally hits a corner of the screen exactly 📐

🏓 Pong App

Pong.js The game that started the entire video game industry. Atari released Pong back in 1972, and it's the title that turned video games into a mass phenomenon. Two paddles, a ball, a black background, and a white dashed line down the middle — nothing more was needed to hook people for decades 🕹️

The player controls the left (cyan) paddle with UP/DOWN, and the right (red) one moves on its own. The ball flies between them, bouncing off the paddles and the top and bottom walls. If your opponent doesn't make it in time — you score a point. First to... actually no, the game runs forever, play as long as you can hold out 🏆

Half the code is the familiar mechanic from Bouncing Ball: the ball moves through bx + bvx, bounces off the ceiling and floor by flipping the sign of its velocity. The paddles add everything interesting on top of that base.

🎯 Ball-paddle collision. When the ball touches the left paddle, three conditions are checked at once: did it reach the paddle's x-coordinate (bx - br <= pw + 5), is it at the paddle's height (by >= p1y && by <= p1y + ph), and is it actually flying toward the paddle (bvx < 0). Only if all three are true do we flip bvx and send the ball back. That last check matters more than it looks: without it, the ball would "stick" to the paddle, endlessly flipping direction.

⚡ Speed-up on every hit. After a bounce, bvx gets bumped by an additional 0.3. The longer the rally goes, the faster the ball flies — and the harder it is to keep up. A small detail that turns a sleepy back-and-forth into a real duel.

🤖 The CPU opponent. The right paddle has the simplest AI in the world: every frame it looks at the ball's vertical position and moves toward it at 3 pixels per frame. That's deliberately slower than the player's 4 pixels — otherwise the computer would be unbeatable and the game would lose its fun. The ± 2 pixel "dead zone" stops the paddle from jittering when the ball sits exactly opposite it.

📊 Score counter. If bx < 0 — the ball flew past the left edge, point for the opponent. If bx > w — the other way around, point for the player. Either way, the ball returns to the center of the screen at its starting velocity, and the next rally begins.

🎨 Black background, white center line, colored paddles. Stylistically the program quotes the original 1972 Pong — minimalism that's impossible to ruin. The center line is drawn by a for loop placing one pixel every 10 units of height. Simple and effective ✨

###b class="inline-flex items-center justify-center relative isolate shrink-0 can-focus select-none disabled:pointer-events-none disabled:opacity-50 disabled:shadow-none disabled:drop-shadow-none border-transparent transition font-base duration-300 ease-[cubic-bezier(0.165,0.85,0.45,1)] h-8 w-8 rounded-md backdrop-blur-md _fill_10ocf_9 _ghost_10ocf_96" type="button" aria-label="Copy to clipboard" data-state="closed"###

javascript

// pong.js — Simple Pong game for one player vs CPU
// Left paddle: D-pad UP/DOWN. Press A to exit.

let w = display.width;
let h = display.height;

// Ball
let bx = w / 2;
let by = h / 2;
let bvx = 3;
let bvy = 2;
let br = 4;

// Paddles
let pw = 6;
let ph = 40;
let p1y = h / 2 - ph / 2; // Player (left)
let p2y = h / 2 - ph / 2; // CPU (right)
let pSpeed = 4;

// Score
let score1 = 0;
let score2 = 0;

let running = true;

while (running) {    // --- Input ---    let ctrl = controller.get_state();    if (ctrl.a.just_pressed) {        running = false;    }    if (ctrl.up.pressed) {        p1y = p1y - pSpeed;    }    if (ctrl.down.pressed) {        p1y = p1y + pSpeed;    }    p1y = math.clamp(p1y, 0, h - ph);
    // --- CPU AI ---    let cpuTarget = by - ph / 2;    if (p2y < cpuTarget - 2) {        p2y = p2y + 3;    }    if (p2y > cpuTarget + 2) {        p2y = p2y - 3;    }    p2y = math.clamp(p2y, 0, h - ph);
    // --- Ball physics ---    bx = bx + bvx;    by = by + bvy;
    // Top/bottom bounce    if (by - br < 0 || by + br > h) {        bvy = -bvy;        by = math.clamp(by, br, h - br);    }
    // Left paddle collision    if (bx - br <= pw + 5 && by >= p1y && by <= p1y + ph && bvx < 0) {        bvx = -bvx;        bvx = bvx + 0.3;        bx = pw + 5 + br;    }
    // Right paddle collision    if (bx + br >= w - pw - 5 && by >= p2y && by <= p2y + ph && bvx > 0) {        bvx = -bvx;        bvx = bvx - 0.3;        bx = w - pw - 5 - br;    }
    // Score    if (bx < 0) {        score2 = score2 + 1;        bx = w / 2;        by = h / 2;        bvx = 3;        bvy = 2;    }    if (bx > w) {        score1 = score1 + 1;        bx = w / 2;        by = h / 2;        bvx = -3;        bvy = -2;    }
    // --- Draw ---    display.fill_screen(colors.black);
    // Center line    for (let dy = 0; dy < h; dy = dy + 10) {        display.draw_pixel(w / 2, dy, display.color565(60, 60, 60));    }
    // Paddles    display.fill_rect(5, math.round(p1y), pw, ph, colors.cyan);    display.fill_rect(w - pw - 5, math.round(p2y), pw, ph, colors.red);
    // Ball    display.fill_circle(math.round(bx), math.round(by), br, colors.white);
    // Score    display.set_cursor(w / 2 - 40, 15);    display.set_text_color(colors.cyan);    display.print(score1);    display.set_cursor(w / 2 + 30, 15);    display.set_text_color(colors.red);    display.print(score2);
    display.queue_draw();    util.sleep(0.016);
}

Pong is the perfect starting point for any kind of game experiment. Want Arkanoid? Replace the right paddle with a wall of bricks, and each ball hit knocks one out. Want Air Hockey for two players? Strip out the right paddle's AI and wire up the second player's controls to other buttons. Want soccer? Add another "paddle" and a goal 🥅 The skeleton is already there — the rest is just imagination ⚡

Lilka looks simple at first glance: a screen, some buttons, an SD card. But dig a little deeper and you'll find an entire ecosystem living inside — a microcontroller, an operating system, scripting engines, a dynamic app loader, and a web interface. In this article, we'll break down what it's all made of and how it works together.

📦 Repositories

The project used to live in a single monorepo. Today, the lilka-dev organization on GitHub hosts 16 repositories. The core ones are:

• keira — the operating system for the console
• sdk — the hardware-facing library
• lilka — schematics and documentation for the device itself
• examples — Lua code samples for beginners
• catalog — a website for browsing community apps
• flasher — a static site for flashing Lilka straight from a browser
• keira_dynapp — Example Dynamic app for KeiraOS
• There are also separate repositories for specific firmwares and apps:

• doom_port — a DOOM port
• arduino-nofrendo — an NES emulator with Lilka-specific fixes
• PicoPico — a Pico-8 fantasy console port for Lilka
• mpeg_stream_player — a video stream player
• BLE_Controller — a Bluetooth controller
• IR_module and RF_module — modules for working with infrared and radio signals

🤔 ESP32 and Raspberry Pi Are Not the Same Thing

This question comes up all the time, and Lilka's developer has a short answer: these are fundamentally different things, alike only in that both of them can be programmed.

ESP32 is a microcontroller made by the Chinese company Espressif. A small chip, cheap, low-power, boots in milliseconds. There's no operating system inside in the usual sense, no file system, no monitor, no keyboard. It just runs a single piece of code written into its flash memory — continuously. Lilka uses a specific version: the ESP32-S3-WROOM-1-N16R8, with two Xtensa LX7 cores at 240 MHz, 16 MB of flash, and 8 MB of PSRAM.

Raspberry Pi is a microcomputer. It runs a full Linux-like operating system, has an HDMI output, USB ports, and hundreds of megabytes of RAM. It's a good fit for tasks that need serious computing power: multimedia, web servers, computer vision. But it's significantly more expensive, physically larger, and draws far more power. It simply doesn't fit into a battery-powered device like a handheld console.

In short: ESP32 is for embedded systems and IoT, Raspberry Pi is for tasks that actually need a tiny computer.

⚙️ FreeRTOS and ESP-IDF

The chip on its own is just silicon. To actually work with it, you need a toolset. Espressif packaged one under the name ESP-IDF (Espressif IoT Development Framework) — the official SDK for ESP32 development. It bundles forks of several existing projects adapted to this chip: notably FreeRTOS for multitasking and lwIP for networking.

FreeRTOS is a small real-time operating system (RTOS). Its main job is to give developers the abstraction of threads (in FreeRTOS terminology they're called "tasks," but it's the same idea). Two pieces of code can run "in parallel," and the system handles switching between them.

🧵 How Multitasking Actually Works

The ESP32-S3 has two physical cores. This matters. One core handles screen rendering, the other runs user code. That's why even when your Lua script isn't doing anything special, the display still updates — a separate core takes care of that.

But even with two cores, each one runs multiple tasks in turn, not simultaneously. Switching is handled by the task scheduler — FreeRTOS's planner. Here's how it works: your code runs continuously until it hits a call to sleep(), delay(), or something similar. That's the exact moment the scheduler gets a chance to hand control to another task. So having delays in your program isn't just a convenience — it's a hard requirement. Without them, other tasks will never get CPU time.

One practical consequence: sleep(100) does not guarantee exactly 100 ms. If there's a higher-priority task waiting, yours waits a bit longer. That's normal RTOS behavior.

🛠️ Lilka SDK and KeiraOS

On top of ESP-IDF sits the Lilka SDK — a C++ library that abstracts away the console's hardware. Instead of manually initializing the ST7789 display over SPI or configuring I2S for the MAX98357A audio amplifier, the developer just calls lilka::display.drawText() or lilka::audio.play(). The SDK takes care of all the details.

KeiraOS is the operating system (firmware) for Lilka, built on top of FreeRTOS, ESP-IDF, and the Lilka SDK. The name is a tribute to the developer's cat 🐈. It's what the user sees when they power the device on: the menu, apps, file manager, Wi-Fi utilities.

KeiraOS's job, in the developer's own words, is more applied than systems-level: take everything that's available and turn it into something anyone can understand. All under tight memory constraints — 8 MB of PSRAM isn't as much as it sounds.

🧩 Apps, services and firmwares

KeiraOS has two core abstractions — app and service. Both are implemented as separate RTOS tasks. An app is what the user launches: a game, a utility, a script. It takes the foreground, reads button input, and draws to the screen. A service is a background task that runs in parallel. The Wi-Fi service keeps the network connection alive while the user plays a game. The web manager service handles HTTP requests from a browser. Services don't have a UI — they just run. 

✍️ How to write an app

Apps for KeiraOS can be written in three languages: 

Lua — the main and recommended option. Lua is a perfect fit for microcontrollers: fast, lightweight, minimal memory footprint. Write a .lua file in any text editor, drop it onto the SD card, and KeiraOS will run it immediately. Most of Lilka's API has Lua bindings. 

mJS — a JavaScript engine from Mongoose OS. The syntax is familiar, but standard JS libraries (React, Node modules, and the like) aren't supported — only basic syntax and microcontroller-specific APIs. Perfectly fine for simple scripts. 

C++ — the option for maximum performance. The app is written as a class that inherits from App, compiled together with Keira itself, and becomes part of it. After that, you have to reflash Lilka. Apps like these run the fastest and have full access to the Lilka library, the Arduino framework, and ESP-IDF. 

🧪 DynApp — dynamic C++ loading 

There's another approach for C++ that's currently in development — DynApp. Instead of compiling the app into Keira itself, you can build it separately as a .so file (Shared Object, as on Linux), drop it onto the SD card, and launch it from the file manager. No reflashing. 

Here's how it works: a built-in ELF loader reads the .so from the card, loads it into PSRAM, links it against the system API, and executes it on the fly. When the app closes, the memory is freed. This is genuinely exciting, because it gives C++ developers the same convenience Lua offers: write, compile, drop the file, launch. The feature is still under active development, but it already works. 

🚀 Multiboot — running third-party firmwares 

Separately from apps, KeiraOS can launch full firmwares — monolithic .bin files that are technically a complete replacement for KeiraOS itself. For example, the DOOM port, Lilradio, Lilka Game Boy Printer, or the Nofrendo NES emulator. 

Technically, these aren't apps: when such a firmware is launched, KeiraOS is fully unloaded, and the chip runs the new code as a single program. But from the user's perspective it looks like any other menu item: pick DOOM → play → exit → back to KeiraOS. The return happens through the OTA mechanism at the next reboot. So even though architecturally it's something entirely different, in practice Multiboot firmwares feel like just another kind of "app." More on specific firmwares in a separate article. 

🔌 GPIO, PIN, and the Expansion Port

GPIO (General Purpose Input/Output) is the general name for a microcontroller's programmable pins. PIN is a specific physical contact on the chip or connector. The distinction is simple: the VBus pin, for instance, is just a power rail — it isn't a GPIO. A GPIO is specifically a pin you can assign a function to in software.

The ESP32-S3 has a so-called Pin Matrix — a flexible system that lets you assign different functions (I2C, SPI, UART, and others) to almost any physical pin. Every GPIO can be configured as a digital input or output, as an ADC (Analog-to-Digital Converter), a DAC (Digital-to-Analog), a PWM output (Pulse-Width Modulation), or as one of the serial interfaces.

A quick rundown of the protocols:

SPI (Serial Peripheral Interface) — a fast protocol for connecting a single peripheral: a display, an SD card. Uses four lines: MOSI, MISO, SCK, CS.

I2C (Inter-Integrated Circuit) — slower, but lets you connect many devices to a single bus (just two lines: SDA and SCL), each with its own unique address. Great for sensors.

UART (Universal Asynchronous Receiver-Transmitter) — a serial protocol for talking to a computer or another device. Two lines: TX and RX.

The expansion port on Lilka is a set of free GPIO pins routed to a connector. This is where external modules plug in: sensors, servos, relays, ultrasonic rangefinders, and the like.

📌 Console Pinout

Conclusion

Lilka isn't some magic box with a screen. It's an ESP32, with FreeRTOS running on it, ESP-IDF on top of that, then the Lilka SDK, and above everything else — KeiraOS, with its menu, apps, and web interface. Each layer has its own job, and once you understand what each one does, the rest of the documentation stops looking like a pile of cryptic jargon.

This is the second article dedicated to Lua programming for Lilka. The first article can be found here. When you start working with sensors, you almost immediately run into strange terms like High and Low. It might sound complicated, but in reality, it’s much simpler Just imagine a regular light switch: it’s either on or off. In electronics, that’s exactly what High and Low mean.

High means there is voltage on the pin — in other words, the signal is “on” ⚡ For a microcontroller, this is usually a logical one. Low, on the other hand, means there is no voltage (or it’s very low), which corresponds to a logical zero. So any simple sensor communicates with your device using this same language: either “yes” or “no.”

On Lilka, this feels especially intuitive. Press a button — you get High  Release it — Low. A motion sensor detects movement — High again. Nothing happens — Low  Even though these terms are rooted in electrical concepts, it’s enough at the beginning to think of them as just two states your device constantly switches between.

This simple idea is the foundation for most of the examples that follow. Once you get it, working with sensors stops feeling complicated and starts to feel more like building with a constructor set  where everything is logical and predictable.

Relay Control on Lilka 🔌

This program turns a CW-020 relay on and off using button A on the Lilka console. A relay is an electrical switch that can control external devices: a light bulb, a fan, and so on ⚡. The module has a low level trigger — it activates when the INpin receives a low signal (~0V). That's why the program immediately sets HIGH on startup, so the relay doesn't accidentally switch on during boot. Button A toggles the relay, button B turns the relay off and exits the program. The screen shows the current state: green "State: ON" or red "State: OFF" 🟢🔴.

Wiring:

local relay_pin = 12
local relay_on = false

function lilka.init()
    gpio.set_mode(relay_pin, gpio.OUTPUT)
    gpio.write(relay_pin, gpio.HIGH)
end

function lilka.update(delta)
    local state = controller.get_state()

    if state.a.just_pressed then
        if relay_on then
            relay_on = false
            gpio.write(relay_pin, gpio.HIGH)
        else
            relay_on = true
            gpio.write(relay_pin, gpio.LOW)
        end
    end

    if state.b.just_pressed then
        gpio.write(relay_pin, gpio.HIGH)
        util.exit()
    end
end

function lilka.draw()
    display.fill_screen(display.color565(0, 0, 0))

    display.set_text_color(display.color565(255, 255, 255))
    display.set_cursor(10, 32)
    display.print("Relay control")

    if relay_on then
        display.set_text_color(display.color565(0, 200, 0))
    else
        display.set_text_color(display.color565(200, 0, 0))
    end
    display.set_cursor(10, 64)
    display.print(relay_on and "State: ON" or "State: OFF")

    display.set_text_color(display.color565(255, 255, 255))
    display.set_cursor(10, 100)
    display.print("A - toggle")
    display.set_cursor(10, 120)
    display.print("B - exit")
end

HC-SR04P Distance Sensor on Lilka 📡

This program measures the distance to an object using the HC-SR04P ultrasonic sensor and displays the result in centimeters on the Lilka screen. The sensor works like a bat 🦇 — it sends an ultrasonic pulse and waits for the echo. The farther the object, the longer the sound travels. The program measures this time and converts it into centimeters.

The key technical challenge — Lua has no built-in microsecond delay, but the sensor requires one. The solution is simple: util.sleep(0.001) gives a 1ms pulse — 100× more than the required 10µs minimum, and perfectly stable ⚙️. Readings are smooth thanks to averaging of eight measurements and an outlier filter — no sudden jumps to 800 cm 🚫. If the sensor is not connected, the screen shows a wiring guide. Button B to exit.

local TRIG = 12
local ECHO = 13

local BLACK = display.color565(0,   0,   0)
local WHITE = display.color565(255, 255, 255)
local GREEN = display.color565(0,   200, 80)
local CYAN  = display.color565(0,   220, 220)
local GRAY  = display.color565(140, 140, 140)

local SMOOTH_N = 8
local MISS_MAX = 16   -- consecutive misses before showing wiring guide
local JUMP_MAX = 40   -- max allowed change per measurement (cm)

local samples    = {}
local miss_count = 0
local distance   = nil

local function measure()
    -- Send TRIG pulse: LOW -> HIGH -> LOW
    -- 1ms = 1000us, sensor needs minimum 10us, so 1ms is well within spec
    gpio.write(TRIG, gpio.LOW)
    util.sleep(0.001)
    gpio.write(TRIG, gpio.HIGH)
    util.sleep(0.001)
    gpio.write(TRIG, gpio.LOW)

    -- Wait for ECHO to go HIGH (start of echo pulse)
    local t = util.time()
    while gpio.read(ECHO) == 0 do
        if util.time() - t > 0.1 then return nil end
    end

    -- Measure how long ECHO stays HIGH
    local t_start = util.time()
    while gpio.read(ECHO) == 1 do
        if util.time() - t_start > 0.1 then return nil end
    end

    -- distance (cm) = duration (s) x speed of sound (cm/s) / 2
    return (util.time() - t_start) * 34300 / 2
end

function lilka.init()
    gpio.set_mode(TRIG, gpio.OUTPUT)
    gpio.set_mode(ECHO, gpio.INPUT)
    gpio.write(TRIG, gpio.LOW)
end

function lilka.update(delta)
    if controller.get_state().b.just_pressed then util.exit() end

    local result = measure()

    if result then
        miss_count = 0

        -- Outlier filter: if new value differs from current by more than
        -- JUMP_MAX cm — ignore it. Buffer stays unchanged, display is stable.
        if distance and math.abs(result - distance) > JUMP_MAX then
            return
        end

        table.insert(samples, result)
        if #samples > SMOOTH_N then table.remove(samples, 1) end
        local sum = 0
        for _, v in ipairs(samples) do sum = sum + v end
        distance = math.floor(sum / #samples)
    else
        miss_count = miss_count + 1
        if miss_count >= MISS_MAX then
            samples  = {}
            distance = nil
        end
    end
end

local function draw_bar(dist)
    if not dist then return end
    local W = display.width
    local bar = dist * (W - 20) / 50
    if bar > W - 20 then bar = W - 20 end
    display.fill_rect(10, 160, bar, 14, CYAN)
    display.draw_rect(10, 160, W - 20, 14, GRAY)
end

function lilka.draw()
    local W = display.width
    local H = display.height
    display.fill_screen(BLACK)

    display.set_font("9x15")
    display.set_text_color(WHITE)
    display.set_cursor(10, 24)
    display.print("HC-SR04P")

    if distance then
        display.set_font("10x20")
        display.set_text_size(3)
        display.set_text_color(GREEN)
        display.set_cursor(10, 110)
        display.print(distance .. " cm")
        display.set_text_size(1)
    else
        local R = W // 2 + 10  -- right column (sensor)
        local L = 10            -- left column (lilka)

        display.set_font("6x13")
        display.set_text_color(GRAY)
        display.set_cursor(10, 44)
        display.print("No sensor detected.")
        display.set_cursor(10, 60)
        display.print("Connect HC-SR04 (5V) or")
        display.set_cursor(10, 76)
        display.print("HC-SR04P (3.3V):")

        -- Column headers
        display.set_font("6x13")
        display.set_text_color(CYAN)
        display.set_cursor(L, 104)
        display.print("Lilka")
        display.set_cursor(R, 104)
        display.print("HC-SR04")

        -- Wiring rows
        display.set_text_color(WHITE)
        local rows = {
            {"3.3V",  "VCC"},
            {"GND",   "GND"},
            {"Pin 12","Trig"},
            {"Pin 13","Echo"},
        }
        for i, row in ipairs(rows) do
            local y = 104 + i * 18
            display.set_cursor(L, y)
            display.print(row[1])
            display.set_cursor(R, y)
            display.print(row[2])
        end
    end

    draw_bar(distance)

    display.set_font("9x15")
    display.set_text_color(WHITE)
    display.set_cursor(W // 2, H - 20)
    display.print("B - exit")
end

🚦Traffic Light App

This program works with a three-color traffic light module — a black board with three large LEDs: red, yellow, and green 🔴🟡🟢. Button A on Lilka turns the red LED on or off, button B controls the yellow one, button D controls the green one, and button C exits the program.

At the start the program declares three variables: led_pin_r = 21, led_pin_y = 47, led_pin_g = 48. These are convenient names for the pins on Lilka's expansion header where the module's signal wires are connected. Instead of writing the numbers 21, 47, and 48 everywhere, we give them readable names — r for red, y for yellow, g for green.

A pin is a physical contact on the Lilka board 🔌. Each pin can work in two modes: sending voltage outward (OUTPUT) or measuring voltage from outside (INPUT). The gpio.set_mode function selects the mode. The gpio.write function turns the voltage on or off. To use an analogy — gpio.set_mode is like hiring a worker and defining their role: a speaker (OUTPUT — sends a signal) or a listener (INPUT — receives a signal). And gpio.write is the specific command given to that worker: gpio.LOW means be silent (0 volts, LED off), gpio.HIGH means speak up (3.3 volts, LED on) ⚡.

That is why at the beginning of the program gpio.set_mode is called with gpio.OUTPUT for each pin — configuring it as an output. Then immediately gpio.write is called with gpio.LOW — turning the voltage off. This guarantees that all three LEDs are off when the program starts 👍.

After the setup the program enters an infinite while true do loop ♾️. Lilka constantly checks the button states in a circle — very fast, hundreds of times per second. Each time it calls controller.get_state() and checks whether a particular button is pressed.

The most interesting line is gpio.write(led_pin_r, 1 - gpio.read(led_pin_r)) 🧠. This is a simple math trick. gpio.read reads the current state of the pin and returns 1 if the LED is on, or 0 if it is off. Then 1 - 1 = 0 or 1 - 0 = 1. So if the LED was on — it turns off, if it was off — it turns on. One button controls both turning on and turning off at the same time.

Button C executes the break command which exits the loop and ends the program 👋. Without it the program would run forever.

led_pin_r = 21
led_pin_y = 47
led_pin_g = 48

gpio.set_mode(led_pin_r, gpio.OUTPUT)
gpio.write(led_pin_r, gpio.LOW)
gpio.set_mode(led_pin_y, gpio.OUTPUT)
gpio.write(led_pin_y, gpio.LOW)
gpio.set_mode(led_pin_g, gpio.OUTPUT)
gpio.write(led_pin_g, gpio.LOW)
while true do
    if controller.get_state().a.pressed then
        gpio.write(led_pin_r, 1 - gpio.read(led_pin_r))
    end
    if controller.get_state().b.pressed then
        gpio.write(led_pin_y, 1 - gpio.read(led_pin_y))
    end
    if controller.get_state().d.pressed then
        gpio.write(led_pin_g, 1 - gpio.read(led_pin_g))
    end
    if controller.get_state().c.pressed then
        break
    end
end

Simple Touch Sensor Button

This program is the simplest possible example of working with a touch sensor that behaves like a regular button. It continuously checks the state of a single pin connected to the sensor and simply displays the result on the Lilka screen.

When you touch the sensor, a signal appears on the pin — that’s the same as High. The program reads this value and understands that a touch has occurred, so it shows “TOUCHED” on the screen  When you release it, the signal disappears (Low), and the screen displays “NOT TOUCHED”.

The logic here is as simple as it gets: there are only two states, constantly changing depending on whether you are touching the sensor or not. The program doesn’t store history, count presses, or add any complexity — it just “looks” at the pin right now and immediately shows the result.

This example clearly demonstrates the core idea of working with sensors: you read a value and react to it. It’s the first step toward more advanced projects, where instead of displaying text, you might control LEDs, servo motors, or even entire smart home systems.

touch_signal_pin = 12

gpio.set_mode(touch_signal_pin, gpio.INPUT)

function lilka.update()
    if controller.get_state().c.just_pressed then
        util.exit()
    end
end

function lilka.draw()
    display.fill_screen(display.color565(0, 0, 0))
    display.set_cursor(10, 32)
    local signal = gpio.read(touch_signal_pin)
    if signal == 1 then
        display.print("TOUCHED")
    else
        display.print("NOT TOUCHED")
    end
end

🌱 Soil Moisture Sensor

This program measures soil moisture using the Capacitive Soil Moisture Sensor v1.2 and displays the result as a percentage on the Lilka screen.

There are two common types of soil moisture sensors. Resistive sensors measure the resistance between two metal probes inserted into the soil — the more moisture, the lower the resistance. They are cheap but have a significant drawback: the metal probes rust in moist soil within just a few weeks 🦀. Capacitive sensors measure the dielectric permittivity of the soil without direct metal contact with moisture — so they last much longer and are a more reliable choice for permanent use.

The sensor connects to an analog pin on Lilka and returns a raw number from 0 to 4095 — this is the ADC value. The capacitive sensor has inverted logic: the lower the number, the more moisture is in the soil. The program converts this raw value into a percentage using a simple formula where DRY is the value in dry air (0%) and WET is the value in water (100%). Both the percentage and the raw ADC value are shown on the screen — useful for calibrating to your specific module 🔧.

Readings are smooth thanks to averaging of eight measurements — the number changes gradually without sudden jumps. On startup the program shows a wiring guide. Press A to start measuring. Button B to exit.

Pin 13 is used for analog reading. On ESP32-S3, the first 20 GPIO pins have a built-in ADC. Pins 12, 13 and 14 on Lilka's expansion header belong to this group — making them the natural choice for analog sensors.

Wiring 🔌

-- Capacitive Soil Moisture Sensor v1.2
-- Wiring: VCC=3.3V, GND=GND, AOUT=pin 13
--
-- Typical calibration values for v1.2 at 3.3V:
-- DRY_AIR  ~3400 (sensor in open air)
-- WET      ~800  (sensor fully submerged in water)
-- Adjust these two constants if readings seem off.

local SENSOR_PIN = 13
local DRY        = 2634   -- ADC value in dry air = 0%
local WET        = 800    -- ADC value in water   = 100%

local BLACK = display.color565(0,   0,   0)
local WHITE = display.color565(255, 255, 255)
local CYAN  = display.color565(0,   220, 220)
local GRAY  = display.color565(140, 140, 140)

-- Smoothing: average of last SMOOTH_N readings
local SMOOTH_N = 8
local samples  = {}

local raw      = 0    -- latest raw ADC value
local moisture = 0    -- smoothed moisture percent (0-100)

local function read_moisture()
    local value = gpio.analog_read(SENSOR_PIN)

    -- Add to smoothing buffer
    table.insert(samples, value)
    if #samples > SMOOTH_N then table.remove(samples, 1) end

    -- Average the buffer
    local sum = 0
    for _, v in ipairs(samples) do sum = sum + v end
    local avg = sum / #samples

    raw = math.floor(avg)

    -- Map ADC value to 0-100%
    -- Sensor is inverted: lower ADC = more moisture
    local pct = (DRY - avg) * 100 / (DRY - WET)
    if pct < 0   then pct = 0   end
    if pct > 100 then pct = 100 end

    moisture = math.floor(pct)
end

local function draw_bar(pct)
    local W = display.width
    local bar = pct * (W - 20) / 100
    display.fill_rect(10, 170, bar, 14, CYAN)
    display.draw_rect(10, 170, W - 20, 14, GRAY)
end

function lilka.init()
    gpio.set_mode(SENSOR_PIN, gpio.INPUT)
end

function lilka.update(delta)
    if controller.get_state().b.just_pressed then util.exit() end
    read_moisture()
end

function lilka.draw()
    local W = display.width
    local H = display.height
    display.fill_screen(BLACK)

    -- Title
    display.set_font("9x15")
    display.set_text_color(WHITE)
    display.set_cursor(10, 24)
    display.print("Soil moisture")

    -- Large percent value
    display.set_font("10x20")
    display.set_text_size(3)
    display.set_text_color(CYAN)
    display.set_cursor(10, 100)
    display.print(moisture .. " %")
    display.set_text_size(1)

    -- Raw ADC value
    display.set_font("6x13")
    display.set_text_color(GRAY)
    display.set_cursor(10, 148)
    display.print("ADC: " .. raw)

    -- Bar
    draw_bar(moisture)

    -- Exit hint
    display.set_font("9x15")
    display.set_text_color(WHITE)
    display.set_cursor(W // 2, H - 20)
    display.print("B - exit")
end

Lilka is an ESP32 console that makes it easy to create your own apps. Once your app is ready, you can publish it to the catalog at catalog.lilka.dev.

You will need a GitHub account. Fun fact: GitHub is built on Git, a protocol created by Linus Torvalds, the author of the Linux kernel. I will show you how to add an app directly through the browser, without installing any additional software.

1. Create Your Own Repository

First, you need a GitHub account. Go to github.com and sign up — it's free.

Once registered, create a repository for your app's code. Click New repository, choose a name, check Add a README file and click Create repository.

2. Add Files to Your Repository

Once the repository is created, you can edit the README.md file by clicking the pencil icon in the upper right corner — add a short description of your app. When done, click the green Commit changes button in the upper right corner to save. The README file uses Markdown format — a simple and easy-to-understand text markup language.

You can write the description yourself, use an online editor like markdownlivepreview.com or stackedit.io, or ask an AI to generate a Markdown description for GitHub based on your code.

Add your code file by clicking Add file → Create new file in the upper right corner. At the top of the screen, enter the file name, for example timer.lua, and paste your code. Then click the green Commit changes button in the upper right corner.

3. Fork the Catalog Repository

To make changes to any existing repository, you need to copy it to your own space — create a fork — make your changes, and then send them for review to the repository owner.

To fork the App Catalog, go to github.com/lilka-dev/catalog and click the Fork button with the fork icon in the upper left corner of the screen. This creates a copy of the catalog in your GitHub account. 

4. Add DESCRIPTION.md

Once forked, the repository will appear in your repository list under the same name lilka-dev/catalog. Open it, navigate to the apps folder and click Add file → Create new file in the upper right corner.

Enter the file name as timer/DESCRIPTION.md — this automatically creates a folder named timer with the file inside. This file is the app description for the Lilka Catalog and can be a full copy of the README.md from your own repository created earlier.

5. Add manifest.yml

The last required file is manifest.yml. It is essentially the app's passport: the catalog uses it to find out the name, author, where the code is located and which files need to be downloaded to the console. Without this file the app will not appear in the catalog.