ak-mcu-base — Firmware source base cho STM32L151

Tiếng Việt · English

Nền firmware bare-metal cho STM32L151CBT6 (AK Base Kit): kernel AK hướng sự kiện không cần RTOS, bootloader có quay lui, cập nhật firmware qua UART và RS485. Dựng lại từ ak-base-kit-stm32l151 của AK Foundation.

Ảnh động ở trên không phải ảnh chụp: nó được dựng từ chính mã vẽ của firmware. Và hai nút bên dưới nó chạy đúng mã C đó trong trình duyệt, không cần kit.

Muốn…	Vào đây
Xem nó chạy	Một kit, đủ 17 màn hình · hai kit chơi Pong với nhau
Hiểu bên trong, không cần biết code	Dừng firmware, chạy từng bước: xem từng message đi từ đâu tới đâu, trên firmware thật chạy trong trang
Lập trình bằng kéo thả	Nối các khối lại, bấm Chạy: chạy ngay trên kit trong trang, gửi được sang kit thật qua USB
Biết demo có gì	Từng màn hình, kèm ảnh động
Bắt đầu dự án mới	python tools/new_project.py <thư-mục> --board <tên-board> · hướng dẫn
Tải firmware	Releases
Đọc tổng quan	Trang giới thiệu

Phần cứng: AK Base Kit

STM32L151CBT6, màn hình OLED 1,54 inch 128×64, ba nút bấm, còi, RTC có pin, flash SPI 1 MB, RS485, UART, I2C, USB Type-C có sẵn mạch USB–UART. Hai ảnh trên là bản dựng từ file thiết kế bo 3.0, không phải ảnh chụp. Ảnh và sơ đồ bo: AK Foundation (giấy phép MIT).

Trên bo có gì

Chân nào làm việc gì

Sơ đồ đã đối chiếu với schematic AK MCU KIT 3.0 và khớp với cấu hình chân trong firmware (src/port/stm32l151). Sinh bởi tools/pinout_svg.py.

Các cổng nối

Theo schematic AK MCU KIT 3.0, sinh bởi tools/connectors_svg.py. Bảng chân dạng chữ: demo-kit.md.

Cây nguồn

Phần mềm: một mã nguồn, ba nơi chạy

Sơ đồ bộ nhớ, luồng cập nhật firmware và cách demo chạy trên kernel: xem docs/ak-mcu-base.md và tài liệu demo.

Bắt đầu nhanh

Cần PlatformIO và ST-Link (hoặc chỉ một máy tính, nếu chỉ chạy test).

pio run -e boot -t upload      # 1. bootloader, 0x08000000
pio run -e demo -t upload      # 2. demo trên AK Base Kit (hoặc -e app: app mẫu, Modbus slave)
pio device monitor             # console UART1, 115200: gõ help

Từ lần sau cập nhật qua cổng console, không cần ST-Link: python tools/ak_fw.py --port COMx flash .pio/build/demo/app.img. Từ điện thoại Android: app trong tools/android/.

Chạy test và bộ giả lập trên máy tính (Linux / WSL): make test, make sim. Dự án mới: python tools/new_project.py <thư-mục> --board <tên-board> xuất một dự án độc lập, không dính repo này. File .img và .bin của mọi bản: Releases.

Tài liệu

Việc	Đọc
Kiến trúc, bản đồ flash, bootloader và OTA, đã kiểm gì	docs/ak-mcu-base.md
Demo trên kit: 17 màn hình, lập trình kéo thả, phần cứng, cách viết màn hình mới	docs/demo-kit.md
Nhật ký sự cố, giám sát task, đo stack, tạo dự án mới, CI	docs/tien-ich.md
Modbus RTU trên RS485: slave, master, OTA	docs/modbus.md
Port sang chip khác; port thứ hai STM32G071 chạy trong Renode	docs/porting.md
Hướng phát triển tiếp: rollback, ký số, Modbus TCP, log flash, chip thứ hai	docs/huong-phat-trien.md · tối ưu nền · tối ưu theo số đo, sau v1.3.9
Phương án dùng base làm tay điều khiển drone và FC cho drone chổi than cỡ nhỏ	docs/drone-ak-mcu.md
Biết bản nào sửa lỗi gì	CHANGELOG.md
Cho AI assistant tra tài liệu kernel AK	docs/ak-mcp-docs-server.md — repo có sẵn

Cấu trúc thư mục

ak-mcu-base/
├── src/            mã nguồn firmware
│   ├── kernel/     kernel AK: task, message, timer, fsm, tsm
│   ├── hal/        giao diện phần cứng mà mọi port phải có
│   ├── common/     xprintf, CRC, log
│   ├── services/   fw (ảnh, OTA, boot_ctrl) · sys (nhật ký sự cố) · modbus
│   ├── boot/       bootloader, không phụ thuộc chip
│   ├── app/        app mẫu: watchdog và giám sát task, shell, OTA  ← dự án viết task ở đây
│   ├── demo/       demo trên AK Base Kit (OLED, 3 nút, còi)
│   └── port/       stm32l151 (chip) · host (máy tính, ak_sim) · web (WebAssembly)
├── tests/          unit test và test đầu-cuối trên ak_sim
├── tools/          ak_fw.py, ak_mb.py, mkimage.py, new_project.py, app Android (android/), tool cho demo và sơ đồ
├── third_party/    nanoMODBUS · SPL + CMSIS của STM32L1 mà bản build dùng
├── docs/           tài liệu và trang web (GitHub Pages)
├── legacy/         base cũ (v1.3.0), chỉ còn bảo trì
├── platformio.ini  build bằng PlatformIO: env boot, app, app_mbmaster, demo
└── CMakeLists.txt  build bằng CMake, test trên máy tính

Trong tài liệu và chú thích mã, đường dẫn kiểu port/stm32l151, demo/scr_pong.c, services/fw là tính từ src/.

Base cũ nằm ở legacy/

Đến 07/10/2026 repo này tên là ak-base-kit-pio và có hai base nằm cạnh nhau: base cũ ở gốc repo (thư mục sources/) và base mới trong ak-mcu-base/. Nay base mới ở gốc repo, base cũ chuyển nguyên vẹn vào legacy/ cho các dự án đang chạy trên nó, và repo đổi tên thành ak-mcu-base (GitHub tự chuyển hướng địa chỉ cũ; riêng trang web chuyển sang hohoanganh.github.io/ak-mcu-base, địa chỉ cũ không còn). Các tag cũ (v1.0.0 … v1.3.0, ak-mcu-base-v1.x) vẫn giữ cấu trúc thư mục của thời điểm đó.

	Base này (gốc repo)	legacy/ — base cũ
Phiên bản	v1.3.11, bootloader 1.4.0	v1.3.0, bootloader 0.0.3
Dùng khi	Dự án mới: OTA an toàn khi mất điện, có unit test, dễ chuyển sang chip khác	Dự án đang chạy trên nó; cần driver có sẵn (EEPROM ngoài, nRF24, lớp Arduino…)
Mức hoàn thiện	Kernel, bootloader, OTA, Modbus RTU, nhật ký sự cố, demo trên kit; driver khác tự viết thêm	Đầy đủ, đã dùng cho sản phẩm
Build	PlatformIO hoặc CMake	PlatformIO (cd legacy)
Cập nhật firmware	UART và RS485 (Modbus); ảnh có CRC32, tên board, chống cài dở	UART, RS485 (Modbus), flash SPI ngoài
Kiểm thử trên máy tính	Kernel, bootloader, Modbus, OTA đầu-cuối trên giả lập, màn hình demo	Lớp Modbus

So sánh chi tiết, kèm những gì base mới còn thiếu: xem trang so sánh · bản Markdown: docs/so-voi-base-cu.md.

Nguồn gốc

• Base: the-ak-foundation/ak-base-kit-stm32l151 (AK Embedded Base Kit, GaoKong), bản build bằng Makefile.
• Mô hình PlatformIO (build ngoài repo, script cờ biên dịch, tự chép release) rút từ một dự án sản phẩm trước đó, không công khai.

Giấy phép

MIT. Kernel AK và phần dựng lại từ ak-base-kit-stm32l151 giữ thông báo bản quyền của AK Foundation (cũng MIT). Mã bên thứ ba trong third_party/ và src/port/web/vendor/ theo giấy phép riêng ghi trong thư mục của chúng.