Skip to content

Commit e487e45

Browse files
pdscompsuchmememanyskill
pdscomp
and
suchmememanyskill
authored
Add UART Serial Console Support for OpenCentauri (oc239) (#67)
* Candidate for oc239 serial UART patch updates for OpenCentauri * Adding reference Device Tree files from CC2 * In-progress, working refactor of uart/uboot stuff * Latest zip file * Make edits more clear with comments --------- Co-authored-by: Sims <38142618+suchmememanyskill@users.noreply.github.com>
1 parent 7938ec8 commit e487e45

21 files changed

+14721
-7
lines changed

‎oc-patches/patch_config‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,4 +30,6 @@ WAIT_FOR_CHAMBER_TEMP=true
3030
REPORT_FILAMENT_USAGE=true
3131
OTA_UPDATES=true
3232
UPLOAD_DURING_PRINTING=true
33-
FIX_UTF8_CORRUPTION=true
33+
UBOOT=true
34+
UART=true
35+
FIX_UTF8_CORRUPTION=true

‎oc-patches/uart-patch/patch.sh‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,21 @@
11
#!/bin/bash
22

3-
# Note: This patch currently disables the scree on the Elegoo CC making it un-usable for printing
4-
# We are working on an updated uBoot binary that will enable UART and also allow screen use!
5-
# For now this is only useful for devs doing DSP or Kernel development.
3+
# This patch enables UART on the Linux side via edits to the rootfs!
64

75
set -e
8-
cd "$REPOSITORY_ROOT"
9-
OPTIONS_DIR="./RESOURCES/OPTIONS" ./RESOURCES/OPTIONS/uart/uart.sh . 2.3.9
6+
7+
project_root="$REPOSITORY_ROOT"
8+
9+
# Source the utils.sh file for ROOTFS_DIR and other variables
10+
source "$project_root/TOOLS/helpers/utils.sh" "$project_root"
11+
12+
# Overwrite the inittab file to enable UART console
13+
echo -e "${YELLOW}INFO: Overwriting the inittab file for UART console ...${NC}"
14+
15+
cat <<EOF >"$ROOTFS_DIR/etc/inittab"
16+
::sysinit:/etc/init.d/rcS S boot
17+
::shutdown:/etc/init.d/rcS K shutdown
18+
::askconsole:/bin/ash --login
19+
EOF
20+
21+
echo -e "${GREEN}INFO: UART console has been enabled in inittab ${NC}"

‎oc-patches/uart-patch/patch.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
id = "uart"
22
name = "Enable Uart"
33
compatible_versions = ["1.1.25", "1.1.40"]
4-
after = ["base"]
4+
after = ["base", "uboot"]

‎oc-patches/uboot-patch/patch.sh‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
#!/bin/bash
2+
3+
# This patch installs the UART-enabled UBoot and boot0 binaries
4+
# The magic to build these live in the uboot/ dir in this repo!
5+
6+
set -e
7+
8+
project_root="$REPOSITORY_ROOT"
9+
10+
# Source the utils.sh file for variables and helper functions
11+
source "$project_root/TOOLS/helpers/utils.sh" "$project_root"
12+
13+
# Check required tools
14+
check_tools "unzip"
15+
16+
# Define paths
17+
uboot_zip_file="$project_root/uboot/uboot.zip"
18+
target_folder="$project_root/unpacked"
19+
20+
# Check the uboot zip file exists
21+
if [ ! -f "$uboot_zip_file" ]; then
22+
echo -e "${RED}ERROR: Cannot find the file '$uboot_zip_file' ${NC}"
23+
exit 1
24+
fi
25+
26+
# Check the target folder exists
27+
if [ ! -d "$target_folder" ]; then
28+
echo -e "${RED}ERROR: Cannot find the target folder '$target_folder' ${NC}"
29+
exit 2
30+
fi
31+
32+
echo -e "${YELLOW}INFO: Installing UART-enabled UBoot and boot0 files ...${NC}"
33+
echo -e "${YELLOW}INFO: Extracting to $target_folder ...${NC}"
34+
35+
# Unzip the uboot package into the target folder
36+
unzip -oq "$uboot_zip_file" -d "$target_folder"
37+
38+
echo -e "${GREEN}INFO: UART-enabled UBoot and boot0 have been installed ${NC}"

‎oc-patches/uboot-patch/patch.toml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
id = "uboot"
2+
name = "Install UART-enabled UBoot"
3+
compatible_versions = ["1.1.25", "1.1.40"]
4+
after = ["base"]

‎uboot/README.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# AnyCubic Centauri Carbon - UART Bootloader Patch (OC2.3.9)
2+
3+
This directory contains tools and configuration for enabling UART serial console support on the AnyCubic Centauri Carbon 3D printer running firmware OC2.3.9 (based on Allwinner R528).
4+
5+
## Overview
6+
7+
This patch enables **full UART serial console support** in both U-Boot bootloader and Linux kernel while maintaining compatibility with the Centauri Carbon device tree for normal 3D printing operations. The solution merges UART-enabled device tree configurations with the AnyCubic 2.3.9 U-Boot binary.
8+
9+
## Background
10+
11+
The stock AnyCubic firmware does not enable UART0 for serial console access, making debugging and system analysis difficult. This patch:
12+
13+
1. **Adds UART0 configuration** to both SPL (board) and kernel device trees
14+
2. **Enables serial console** at 115200 baud on UART0
15+
3. **Preserves the Centauri Carbon device tree** for LCD, PWM, I2C, and other peripherals
16+
4. **Maintains bootloader integrity** through proper checksum and slot management
17+
18+
## Hardware Connection
19+
20+
UART0 is available on the SD card pins:
21+
- **TX (Transmit)**: PF2 (SD Card DAT0)
22+
- **RX (Receive)**: PF4 (SD Card DAT2)
23+
- **Ground**: SD Card Shield/GND
24+
25+
Use a 3.3V TTL serial adapter. Connect at **115200 8N1**.
26+
27+
## Files
28+
29+
### Device Tree Sources (DTS)
30+
31+
- **`board_config.dts`** - SPL/U-Boot board configuration
32+
- Configures clocks, pinmux, storage controllers
33+
- **UART0 injection** at lines 825-839 with aliases and chosen stdout
34+
35+
- **`kernel_config.dts`** - Main Linux kernel device tree
36+
- Complete R528 device tree with all peripherals
37+
- **UART0 enabled** at lines 1165-1182 (status = "okay")
38+
- Serial console configured in bootargs and aliases
39+
40+
### Tools
41+
42+
- **`repack.py`** - Python script to rebuild U-Boot image
43+
- Compiles `.dts` files to `.dtb` using `dtc` compiler
44+
- Injects DTBs at fixed offsets in U-Boot binary
45+
- Updates checksums and size headers
46+
- Preserves ELF binary placement for bootloader integrity
47+
48+
- **`uboot-generate.sh`** - Master build script
49+
- Executes `repack.py` to build new U-Boot
50+
- Runs validation with `check.sh`
51+
- Packages `boot0` and `uboot` into `uart.zip`
52+
53+
- **`check.sh`** - Validation script
54+
- Verifies ELF magic offsets match between original and patched
55+
- Ensures binary structure integrity
56+
57+
### Binary Files
58+
59+
- **`original_dump.bin`** - Original AnyCubic 2.3.9 U-Boot dump
60+
- **`repacked_boot.bin`** - Generated patched U-Boot (after running scripts)
61+
- **`boot0`** - SPL bootloader (preserved from original)
62+
- **`uboot`** - Final patched U-Boot image
63+
- **`uart.zip`** - Flashable package containing `boot0` and `uboot`
64+
65+
## Usage
66+
67+
### Prerequisites
68+
69+
Install device tree compiler:
70+
```bash
71+
sudo apt-get install device-tree-compiler
72+
```
73+
74+
### Building
75+
76+
Run the generation script:
77+
```bash
78+
./uboot-generate.sh
79+
```
80+
81+
This will:
82+
1. Compile both DTS files to DTB format
83+
2. Inject them into the U-Boot binary at fixed slots
84+
3. Update checksums and headers
85+
4. Validate binary integrity
86+
5. Create `uart.zip` ready for flashing
87+
88+
### Flashing
89+
90+
1. Extract the original AnyCubic firmware update
91+
2. Replace `boot0` and `uboot` with files from `uart.zip`
92+
3. Flash using standard AnyCubic update procedure
93+
94+
**Note**: Boot0 is typically unchanged, but included for completeness.
95+
96+
### Verification
97+
98+
After flashing, connect a serial adapter to UART0 pins and monitor at 115200 8N1. You should see:
99+
- U-Boot boot messages
100+
- Kernel boot log
101+
- Linux login prompt
102+
103+
## Technical Details
104+
105+
### U-Boot Binary Structure
106+
107+
The U-Boot binary has a fixed structure:
108+
109+
```
110+
+-------------------+
111+
| Header (0x800) | <-- Checksums, sizes
112+
+-------------------+
113+
| SPL Code |
114+
+-------------------+
115+
| Slot 1: SPL DTB | <-- Offset 0xD4914, Size 32492 bytes
116+
+-------------------+
117+
| ELF Binary |
118+
+-------------------+
119+
| Slot 2: Main DTB | <-- Offset 0x120000, Size 65535 bytes
120+
+-------------------+
121+
| Trailing Data |
122+
+-------------------+
123+
```
124+
125+
**Critical**: DTBs must be injected at **exact fixed offsets** to preserve relative ELF binary position. Shifting these offsets corrupts the bootloader.
126+
127+
### Checksum Algorithm
128+
129+
Allwinner bootloaders use a simple additive checksum:
130+
1. Write stamp value `0x5F0A6C39` at offset `0x14`
131+
2. Sum all 32-bit words in the binary
132+
3. Write final checksum at offset `0x14`
133+
134+
The `repack.py` script handles this automatically.
135+
136+
### Device Tree Patches
137+
138+
#### Board Config (SPL)
139+
```dts
140+
uart0: uart@2500000 {
141+
compatible = "snps,dw-apb-uart";
142+
reg = <0x00 0x02500000 0x00 0x400>;
143+
reg-shift = <2>;
144+
status = "okay";
145+
};
146+
147+
chosen {
148+
stdout-path = "serial0:115200n8";
149+
};
150+
151+
aliases {
152+
serial0 = &uart0;
153+
};
154+
```
155+
156+
#### Kernel Config
157+
```dts
158+
uart@2500000 {
159+
compatible = "allwinner,sun8i-uart";
160+
status = "okay"; /* Changed from "disabled" */
161+
pinctrl-0 = <0x14>;
162+
pinctrl-1 = <0x15>;
163+
...
164+
};
165+
166+
chosen {
167+
bootargs = "...console=ttyS0...";
168+
};
169+
```
170+
171+
## Troubleshooting
172+
173+
### No Serial Output
174+
- Check wiring: TX ↔ RX, Ground connected
175+
- Verify 3.3V TTL levels (not RS-232!)
176+
- Confirm 115200 8N1 settings
177+
- Test adapter with another device
178+
179+
### Boot Fails After Flashing
180+
- Verify `check.sh` passed before flashing
181+
- Compare file sizes: repacked should match original ±100 bytes
182+
- Re-extract original firmware and try again
183+
184+
### DTC Compilation Errors
185+
- Check `.dts` syntax (no missing braces, semicolons)
186+
- Verify phandle references are valid
187+
- Use `dtc -I dts -O dts -o /dev/null <file>` to validate
188+
189+
## Credits
190+
191+
- Based on AnyCubic OC 2.3.9 firmware for Centauri Carbon
192+
- Allwinner R528 (sun8iw20) platform
193+
- Device tree modifications by cc-fw-tools contributors
194+
195+
## License
196+
197+
These tools are provided as-is for educational and development purposes. Use at your own risk. Always maintain backups of original firmware.
198+
199+
## See Also
200+
201+
- [Allwinner R528 Datasheet](https://linux-sunxi.org/R528)
202+
- [U-Boot Device Tree Documentation](https://u-boot.readthedocs.io/en/latest/develop/devicetree/intro.html)
203+
- [Linux Serial Console Setup](https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html)

0 commit comments

Comments
 (0)