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.
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.
