AK Base Kit

01Tổng quan

Repo gồm hai phần: ak-mcu-base (bản viết lại, tách khỏi chip, có unit test; dự án mới bắt đầu từ đây) và base cũ trong legacy/ (dành cho dự án đang chạy trên nó). Cả hai cùng dựa trên kernel AK.

02Kernel AK hoạt động thế nào

Mỗi task là một active object: có hàng đợi message riêng, chỉ xử lý một message mỗi lần. Ngắt (ISR) không làm việc nặng, chỉ post message rồi thoát. Scheduler luôn chọn task có ưu tiên cao nhất đang có message.

Viết một task

/* task_list.h — thứ tự enum phải khớp bảng */
enum {
    TASK_TIMER_TICK_ID,
    TASK_SYSTEM_ID,
    TASK_SENSOR_ID,      /* task mới */
    AK_TASK_EOT_ID,
};

/* task_list.c */
task_t app_task_table[] = {
  {TASK_TIMER_TICK_ID, TASK_PRI_LEVEL_7, task_timer_tick},
  {TASK_SYSTEM_ID,     TASK_PRI_LEVEL_2, task_system},
  {TASK_SENSOR_ID,     TASK_PRI_LEVEL_3, task_sensor},
  {AK_TASK_EOT_ID,     TASK_PRI_LEVEL_0, (pf_task)0},
};

/* task_sensor.c */
void task_sensor(ak_msg_t* msg) {
    switch (msg->sig) {
    case SENSOR_SIG_INIT:
        /* đọc cảm biến mỗi 500 ms */
        timer_set(TASK_SENSOR_ID, SENSOR_SIG_READ,
                  500, TIMER_PERIODIC);
        break;

    case SENSOR_SIG_READ: {
        uint8_t v = sensor_read();
        task_post_common_msg(TASK_SYSTEM_ID,
                  SYSTEM_SIG_DATA, &v, 1);
    }   break;
    }
}

Kernel tra task theo chỉ số task_table[id], nên dòng thứ n phải mang id = n. Lệch thứ tự thì FATAL("TK", 0x08) ngay lúc khởi động, thay vì để message đi nhầm task.

03Hai nhánh trong repo

Làm sản phẩm ngay thì dùng base v1.3.0. ak-mcu-base là hướng đi tiếp theo: cùng ý tưởng nhưng tách khỏi chip để port sang chip khác, và có test chạy trên máy tính.

04Base ổn định v1.3.0

Dựng lại từ ak-base-kit-stm32l151 (bản gốc build bằng Makefile) theo mô hình PlatformIO đã chạy ổn định trong sản phẩm. Bare-metal, SPL + CMSIS + startup + linker script nằm sẵn trong repo.

Bản đồ flash

Các lớp phần mềm

Build và nạp

pio run -e app                 # firmware ứng dụng (Modbus master, mặc định)
pio run -e app_mbslave         # biến thể Modbus SLAVE (OTA qua RS485)
pio run -e boot                # bootloader
pio run -e boot -t upload      # 1. nạp boot (board trắng phải nạp cả hai)
pio run -e app  -t upload      # 2. nạp app bằng ST-Link
pio device monitor             # console UART1 115200

Cập nhật firmware qua RS485

python -m epcb_applib.ota COMx \
  legacy/release/app_mbslave/ak_base_kit_app_mbslave_v1.3.0.bin \
  --slave 1 --baud 9600

Dùng cho dự án mới

1. Clone theo tag v1.3.0, xoá .git, git init, ghi "Khởi tạo từ ak-base-kit-pio v1.3.0" vào README.
2. Đổi định danh trong platformio.ini: APP_TITLE, APP_VERSION, build_dir, prefix tên file release.
3. Chọn module bằng cờ: TASK_MBMASTER_EN / TASK_MBSLAVE_EN / SERIAL2_EN (USART2 chỉ một chủ), OLED, link UART…
4. Sửa phần cứng theo schematic mới: io_cfg.h/.c, sys_cfg.c.
5. Build thử cả hai env: 0 lỗi, 0 cảnh báo; nạp boot + app, console lên log, LED nháy.
6. Viết chức năng theo mô hình AK: thêm task ID + dòng trong bảng task đúng vị trí, tạo app/task_xxx.cpp.
7. Release: tăng APP_VERSION, build, lấy file trong release/.

05ak-mcu-base v1.3.11

Kernel AK, bootloader và OTA viết một lần, chạy trên mọi chip có port. Code phía trên lớp HAL không include header của chip. Port host chạy unit test và giả lập cả bootloader lẫn app ngay trên máy tính, không cần board.

Bản đồ flash (mặc định, staging ở flash SPI ngoài)

Board không gắn chip SPI: build make stm32-internal → APP 58K + STAGING 58K, cả hai trong flash trong.

Bootloader quyết định thế nào

Chạy thử ngay trên máy tính

cd ak-mcu-base
make test       # unit test + test OTA đầu-cuối trên trình giả lập
make sim        # chạy bootloader + app giả lập: gõ 'help' trong shell
make stm32      # build/stm32l151/{boot.bin, app.img, *.elf}

# nạp firmware qua UART console (board thật hoặc trình giả lập)
python3 tools/ak_fw.py --port /dev/ttyUSB0 flash build/stm32l151/app.img
python3 tools/ak_fw.py --sim build/host/ak_sim info

Đã kiểm gì

README đầy đủ của ak-mcu-base → · Hướng dẫn port sang chip mới →

06Lịch sử phiên bản

Chi tiết từng bản ở CHANGELOG.md.

• ak-mcu-base10/2026

  Base đa nền tảng: kernel AK tách khỏi chip, bootloader + OTA an toàn khi mất điện, ghi half-page, staging trên flash SPI ngoài, port host + trình giả lập.

• v1.3.025/09/2026

  OTA qua Modbus RS485 dùng được thật trên env app_mbslave; đã kiểm trên board (≈ 78 s/lượt @ 9600, cắt ngang vẫn chạy app cũ).

• v1.2.025/09/2026

  Modbus chuyển sang nanoMODBUS (MIT), thêm chế độ slave, bỏ thư viện thương mại, thêm test host.

• v1.1.224/09/2026

  Sửa cờ biên dịch không tới file nguồn, version lấy từ APP_VERSION, kiểm thứ tự bảng task, giới hạn flash theo env.

• v1.1.0 – v1.1.123/09/2026

  Bootloader 0.0.2/0.0.3: tự kiểm bảng vector, tự vá BSF; sửa 11 lỗi (UART, RS485, ADC, GPIO, cờ build).

• v1.0.016/08/2026

  Bản đầu tiên đánh tag: port AK Embedded Base Kit sang PlatformIO, chống ghi đè bootloader khi nạp.

07Tài liệu

Toàn bộ tài liệu viết bằng tiếng Việt, nằm trong repo.