Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions .github/workflows/firmware.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ jobs:
./.pio
key: ${{ runner.os }}-keira

- uses: actions/setup-python@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'

Expand Down Expand Up @@ -98,25 +98,28 @@ jobs:
PLATFORMIO_BUILD_FLAGS=-D$lang pio run -e v2
cp .pio/build/v2/firmware.bin out/keira_${lang}.bin
cp .pio/build/v2/partitions.bin out/partitions.bin
cp .pio/build/v2/bootloader.bin out/bootloader.bin
cp boot/lilka_v2/bootloader.bin out/bootloader.bin
pip install esptool
# boot_app0.bin is a blank otadata: the board starts Keira (app0) after flashing
esptool.py --chip esp32s3 merge_bin \
-o out/KeiraOS_merged_${lang}.bin \
0x0 out/bootloader.bin \
0x8000 out/partitions.bin \
0xe000 ~/.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin \
0x10000 out/keira_${lang}.bin
done
else
echo "Main branch or PR - building for default language only"
pio run -e v2
cp .pio/build/v2/firmware.bin out/keira.bin
cp .pio/build/v2/partitions.bin out/partitions.bin
cp .pio/build/v2/bootloader.bin out/bootloader.bin
cp boot/lilka_v2/bootloader.bin out/bootloader.bin
pip install esptool
esptool.py --chip esp32s3 merge_bin \
-o out/KeiraOS_merged.bin \
0x0 out/bootloader.bin \
0x8000 out/partitions.bin \
0xe000 ~/.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin \
0x10000 out/keira.bin
fi

Expand Down
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,14 @@ KeiraOS, операційна система для консолей [![Lilka](h

## 🛠️ Як прошити Lilka (KeiraOS)

Найпростіше прошити Лілку через [flasher.lilka.dev](https://flasher.lilka.dev/): виберіть версію, підключіть Лілку і натисніть «Прошити».

`KeiraOS_merged*.bin` містить Keira разом із boot-меню та таблицею розділів [lilka-bootloader](https://github.com/lilka-dev/lilka-bootloader):
- затисніть **START** під час увімкнення, щоб вибрати Keira OS, Retro-Go або прошивку з SD-картки;
- Retro-Go встановлюється з самої Keira: відкрийте `retro-go_lilka.img` у файловому менеджері.

Детальніше: [boot/README.md](boot/README.md). Нижче — прошивка вручну через ESPTool.

### 1. Відкрити інструмент прошивки
Перейдіть на сторінку [ESPTool (в браузері)](https://espressif.github.io/esptool-js/)
> ⚠️ Працює лише в Google Chrome або Chromium-браузерах.
Expand Down
27 changes: 27 additions & 0 deletions boot/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Boot menu and partition table

Keira for Lilka v2 is built with the boot menu and the partition table from
[lilka-bootloader](https://github.com/lilka-dev/lilka-bootloader) instead of the stock Arduino ones
(see `platformio.ini`). They're the same on every board, so `KeiraOS_merged*.bin` from the releases
writes all of it at `0x0`, e.g. with [flasher.lilka.dev](https://flasher.lilka.dev/).

- `lilka_v2/bootloader.bin`: boot menu (hold START on reset): Keira OS, Retro-Go, firmware from the SD card
- `lilka_v2/partitions.csv`: Keira `app0`/`app1`, Retro-Go apps, SPIFFS

Retro-Go is installed from Keira: open `retro-go_lilka.img` from the SD card (or the catalog) in the
file manager.

Boards flashed with the stock layout keep it on OTA updates (only the app is updated); flash
`KeiraOS_merged*.bin` once over USB to switch.

## Updating

Built from lilka-bootloader `b070661`:

```bash
make bootloader # in lilka-bootloader
cp bootloader/build-docker/bootloader/bootloader.bin <keira>/boot/lilka_v2/
cp partitions.csv <keira>/boot/lilka_v2/
```

Keep this file's commit reference in sync.
10 changes: 10 additions & 0 deletions boot/bootloader.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# PlatformIO pre-script: build Keira with the lilka-bootloader boot menu (see boot/README.md).
# `board_build.arduino.custom_bootloader` is resolved inside the framework's variants dir,
# so pass it as an absolute path.
from os.path import join

Import("env")

env.BoardConfig().update(
"build.arduino.custom_bootloader", join(env.subst("$PROJECT_DIR"), "boot", "lilka_v2", "bootloader.bin")
)
Binary file added boot/lilka_v2/bootloader.bin
Binary file not shown.
16 changes: 16 additions & 0 deletions boot/lilka_v2/partitions.csv
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Lilka v2 (16 MB): Keira OS + Keira multiboot slot + Retro-Go, booted by lilka_boot.
# Retro-Go finds its apps by label, Keira expects app0/app1 as ota_0/ota_1.
# Name, Type, SubType, Offset, Size
nvs, data, nvs, 0x9000, 0x5000
otadata, data, ota, 0xe000, 0x2000
app0, app, ota_0, 0x10000, 0x400000
app1, app, ota_1, 0x410000, 0x300000
launcher, app, ota_2, 0x710000, 0x100000
retro-core, app, ota_3, 0x810000, 0xd0000
prboom-go, app, ota_4, 0x8e0000, 0xd0000
snes9x, app, ota_5, 0x9b0000, 0xa0000
gwenesis, app, ota_6, 0xa50000, 0x100000
fmsx, app, ota_7, 0xb50000, 0xa0000
gbsp, app, ota_8, 0xbf0000, 0xd0000
spiffs, data, spiffs, 0xcc0000, 0x330000
coredump, data, coredump, 0xff0000, 0x10000
6 changes: 5 additions & 1 deletion platformio.ini
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,11 @@ lib_deps =
bitbank2/AnimatedGIF@2.1.0
bitbank2/JPEGDEC@1.8.4
lib_extra_dirs = ./lib
extra_scripts = targets.py
; Boot menu + partition table shared with Retro-Go, see boot/README.md
extra_scripts =
pre:boot/bootloader.py
targets.py
board_build.partitions = boot/lilka_v2/partitions.csv
build_flags =
-DARDUINO_USB_MODE=1
-DARDUINO_USB_CDC_ON_BOOT=1
Expand Down
151 changes: 151 additions & 0 deletions src/apps/flashimage/flashimage.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
#include "flashimage.h"
#include "keira/keira.h"
#include "keira/ksystem.h"
#include "keira/utils/defer.h"
#include "keira/utils/string.h"

#include <esp_ota_ops.h>

// Layout of a full ESP32 flash image: partition table entries at 0x8000
static constexpr uint32_t IMAGE_PARTITION_TABLE_OFFSET = 0x8000;
static constexpr uint16_t IMAGE_PARTITION_MAGIC = 0x50AA;
static constexpr size_t IMAGE_PARTITION_MAX_ENTRIES = 95;
static constexpr uint8_t IMAGE_PARTITION_TYPE_APP = 0x00;
static constexpr size_t FLASH_SECTOR_SIZE = 4096;

struct __attribute__((packed)) ImagePartitionEntry {
uint16_t magic;
uint8_t type;
uint8_t subtype;
uint32_t offset;
uint32_t size;
char label[16];
uint32_t flags;
};

static_assert(sizeof(ImagePartitionEntry) == 32, "partition table entry is 32 bytes");

FlashImageApp::FlashImageApp(const String& path) : App("FlashImage"), path(path) {
setktStackSize(8192);
}

bool FlashImageApp::isFlashImage(const String& path) {
FILE* file = fopen(path.c_str(), "rb");
if (!file) return false;
Defer closeFile([file]() { fclose(file); });

ImagePartitionEntry entry;
return fseek(file, IMAGE_PARTITION_TABLE_OFFSET, SEEK_SET) == 0 && fread(&entry, sizeof(entry), 1, file) == 1 &&
entry.magic == IMAGE_PARTITION_MAGIC;
}

bool FlashImageApp::collectParts(FILE* file, std::vector<ImagePart>& parts) {
if (fseek(file, 0, SEEK_END) != 0) return false;
uint32_t fileSize = ftell(file);
if (fseek(file, IMAGE_PARTITION_TABLE_OFFSET, SEEK_SET) != 0) return false;

std::vector<ImagePartitionEntry> entries;
ImagePartitionEntry entry;
while (entries.size() < IMAGE_PARTITION_MAX_ENTRIES && fread(&entry, sizeof(entry), 1, file) == 1 &&
entry.magic == IMAGE_PARTITION_MAGIC) {
entries.push_back(entry);
}

const esp_partition_t* running = esp_ota_get_running_partition();
for (const auto& e : entries) {
if (e.type != IMAGE_PARTITION_TYPE_APP || e.offset >= fileSize) continue;
char label[sizeof(e.label) + 1] = {0};
memcpy(label, e.label, sizeof(e.label));

// Only apps that have a home in Keira's partition table, and never Keira itself
const esp_partition_t* target =
esp_partition_find_first(ESP_PARTITION_TYPE_APP, ESP_PARTITION_SUBTYPE_ANY, label);
if (!target || target == running) continue;

uint32_t size = std::min(e.size, fileSize - e.offset);
if (size > target->size) {
error = StringFormat(K_S_FLASHIMAGE_TOO_BIG_FMT, label);
return false;
}
parts.push_back({target, e.offset, size});
}
if (parts.empty()) {
error = K_S_FLASHIMAGE_NO_PARTS;
return false;
}
return true;
}

bool FlashImageApp::writePart(FILE* file, const ImagePart& part, uint32_t& written, uint32_t total) {
uint32_t eraseSize = (part.size + FLASH_SECTOR_SIZE - 1) / FLASH_SECTOR_SIZE * FLASH_SECTOR_SIZE;
esp_err_t err = esp_partition_erase_range(part.target, 0, eraseSize);
if (err != ESP_OK || fseek(file, part.offset, SEEK_SET) != 0) {
error = StringFormat(K_S_FLASHIMAGE_WRITE_ERROR_FMT, part.target->label, esp_err_to_name(err));
return false;
}

uint8_t* buf = static_cast<uint8_t*>(calloc(1, FLASH_SECTOR_SIZE));
if (!buf) {
error = StringFormat(K_S_FLASHIMAGE_WRITE_ERROR_FMT, part.target->label, esp_err_to_name(ESP_ERR_NO_MEM));
return false;
}
Defer freeBuf([buf]() { free(buf); });

lilka::ProgressDialog dialog(K_S_FLASHIMAGE_TITLE, part.target->label);
for (uint32_t off = 0; off < part.size; off += FLASH_SECTOR_SIZE) {
size_t chunk = std::min<uint32_t>(FLASH_SECTOR_SIZE, part.size - off);
if (fread(buf, 1, chunk, file) != chunk) {
error = StringFormat(K_S_FLASHIMAGE_WRITE_ERROR_FMT, part.target->label, "read");
return false;
}
err = esp_partition_write(part.target, off, buf, chunk);
if (err != ESP_OK) {
error = StringFormat(K_S_FLASHIMAGE_WRITE_ERROR_FMT, part.target->label, esp_err_to_name(err));
return false;
}
written += chunk;
dialog.setProgress(static_cast<int64_t>(written) * 100 / total);
dialog.draw(canvas);
queueDraw();
}
return true;
}

void FlashImageApp::run() {
FILE* file = fopen(path.c_str(), "rb");
if (!file) {
alert(K_S_ERROR, StringFormat(K_S_FLASHIMAGE_WRITE_ERROR_FMT, path.c_str(), strerror(errno)));
return;
}
Defer closeFile([file]() { fclose(file); });

std::vector<ImagePart> parts;
if (!collectParts(file, parts)) {
alert(K_S_ERROR, error);
return;
}

String labels;
uint32_t total = 0;
for (const auto& part : parts) {
labels += (labels.isEmpty() ? "" : ", ") + String(part.target->label);
total += part.size;
}
String about =
StringFormat(K_S_FLASHIMAGE_CONFIRM_FMT, labels.c_str(), lilka::fileutils.getHumanFriendlySize(total).c_str());
if (!confirm(K_S_FLASHIMAGE_TITLE, about)) return;

uint32_t written = 0;
for (const auto& part : parts) {
if (!writePart(file, part, written, total)) {
alert(K_S_ERROR, error);
return;
}
}

// Image's first app is its entry point (e.g. Retro-Go's launcher)
const esp_partition_t* entry = parts.front().target;
if (confirm(K_S_FLASHIMAGE_TITLE, StringFormat(K_S_FLASHIMAGE_DONE_FMT, entry->label))) {
KeiraSystem::bootPartition(entry);
}
}
30 changes: 30 additions & 0 deletions src/apps/flashimage/flashimage.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
#pragma once
#include "keira/app.h"

#include <esp_partition.h>
#include <vector>

// Installs the apps of a full flash image (e.g. retro-go_*_lilka.img) into the partitions with the
// same labels. The image's bootloader and partition table are ignored, Keira itself is never touched.
class FlashImageApp : public App {
public:
explicit FlashImageApp(const String& path);

// True when the file looks like a full flash image (partition table at 0x8000)
static bool isFlashImage(const String& path);

void run() override;

private:
struct ImagePart {
const esp_partition_t* target;
uint32_t offset; // in the image file
uint32_t size;
};

bool collectParts(FILE* file, std::vector<ImagePart>& parts);
bool writePart(FILE* file, const ImagePart& part, uint32_t& written, uint32_t total);

String path;
String error;
};
2 changes: 1 addition & 1 deletion src/apps/fmanager/fmanager.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -305,7 +305,7 @@ FMEntry FileManagerApp::pathToEntry(const String& path) {
newEntry.type = FT_NES_ROM;
newEntry.icon = FT_NES_ICON;
newEntry.color = FT_NES_ROM_COLOR;
} else if (lowerCasedPath.endsWith(".bin")) {
} else if (lowerCasedPath.endsWith(".bin") || lowerCasedPath.endsWith(".img")) {
newEntry.type = FT_BIN;
newEntry.icon = FT_BIN_ICON;
newEntry.color = FT_BIN_COLOR;
Expand Down
6 changes: 6 additions & 0 deletions src/apps/keiraupdate/keiraupdate.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,12 @@ void KeiraUpdateApp::install(const FirmwareVersion& fw) {
httpConfig.buffer_size_tx = KEIRA_UPDATE_TX_BUFFER;
httpConfig.keep_alive_enable = true;

// esp_https_ota always writes the next OTA partition, which isn't Keira's when other apps share the flash
if (esp_ota_get_next_update_partition(NULL) != KeiraSystem::getUpdatePartition()) {
alert(K_S_ERROR, K_S_KEIRA_UPDATE_SLOT_ERROR);
return;
}

esp_https_ota_config_t otaConfig = {};
otaConfig.http_config = &httpConfig;

Expand Down
15 changes: 15 additions & 0 deletions src/apps/launcher/launcher.cpp
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
#include <ff.h>
#include <FS.h>
#include <qrcode.h>
#include <esp_ota_ops.h>
#include "keira/utils/mem.h"
#include "keira/keira.h"
#include "launcher.h"
Expand Down Expand Up @@ -68,6 +69,9 @@
#include "keira/ksystem.h"
#include "keira/utils/string.h"

// Partition label of Retro-Go's launcher (see boot/lilka_v2/partitions.csv)
static constexpr const char* RETRO_GO_PARTITION = "launcher";

// Home screen wallpaper, Lua script takes priority over images, first existing image is used
static const char* const WALLPAPER_LUA_PATH = "/sd/wallpaper.lua";
static const char* const WALLPAPER_PATHS[] =
Expand Down Expand Up @@ -146,6 +150,17 @@ void LauncherApp::run() {
appsItems.insert(appsItems.begin(), ITEM::APP(lastOTA.c_str(), [this]() { this->runApp<MultiBootApp>(); }));
}

// Retro-Go installed next to Keira (see FlashImageApp) has its launcher in its own partition.
// The app description check skips empty partitions and leftovers of an older layout.
const esp_partition_t* retroGo =
esp_partition_find_first(ESP_PARTITION_TYPE_APP, ESP_PARTITION_SUBTYPE_ANY, RETRO_GO_PARTITION);
esp_app_desc_t retroGoDesc;
if (retroGo && esp_ota_get_partition_description(retroGo, &retroGoDesc) == ESP_OK) {
appsItems.insert(appsItems.begin(), ITEM::APP(K_S_LAUNCHER_RETRO_GO, [retroGo]() {
KeiraSystem::bootPartition(retroGo);
}));
}

item_t root_item = ITEM::SUBMENU(
K_S_LAUNCHER_MAIN_MENU,
{
Expand Down
2 changes: 1 addition & 1 deletion src/apps/lilcatalog/lilcatalog.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -897,7 +897,7 @@ ExecutionType LilCatalogApp::detectTypeByExtension(const String& location) {
String loc = location;
loc.toLowerCase();
if (loc.endsWith(".lua")) return EXEC_TYPE_LUA;
if (loc.endsWith(".bin")) return EXEC_TYPE_BINARY;
if (loc.endsWith(".bin") || loc.endsWith(".img")) return EXEC_TYPE_BINARY;
if (loc.endsWith(".so")) return EXEC_TYPE_DYNAPP;
if (loc.endsWith(".zip") || loc.endsWith(".tar") || loc.endsWith(".gz")) return EXEC_TYPE_ARCHIVE;
return EXEC_TYPE_UNKNOWN;
Expand Down
6 changes: 4 additions & 2 deletions src/keira/keira.h
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
#include "apps/nes/nesapp.h"
#include "apps/dynapp/dynapp.h"
#include "apps/multiboot/multiboot.h"
#include "apps/flashimage/flashimage.h"
#include "apps/imageviewer/imageviewer.h"
///////////////////////////////////////////////////////////////////////////////////////////////////////
// FILETYPE HANDLERS: ////////////////////////////////////////////////////////////////////////////////
Expand All @@ -39,8 +40,9 @@
#define K_FT_SOUND_HANDLER(X) ksystem.apps.spawn(new MadPlayerApp(X))
#define K_FT_LT_HANDLER(X) ksystem.apps.spawn(new LilTrackerApp(X))
#define K_FT_SO_HANDLER(X) ksystem.apps.spawn(new DynApp(X))
#define K_FT_BIN_HANDLER(X) ksystem.apps.spawn(new MultiBootApp(X))
#define K_FT_IMAGE_HANDLER(X) ksystem.apps.spawn(new ImageViewerApp(X))
#define K_FT_BIN_HANDLER(X) \
ksystem.apps.spawn(FlashImageApp::isFlashImage(X) ? static_cast<App*>(new FlashImageApp(X)) : new MultiBootApp(X))
#define K_FT_IMAGE_HANDLER(X) ksystem.apps.spawn(new ImageViewerApp(X))

///////////////////////////////////////////////////////////////////////////////////////////////////////
// GUIDELINE: Use Keira global filetype handlers(K_FT_) if possible
Expand Down
Loading
Loading