https://github.com/apadevices/apaserialsync
APASerialSync: The Ultimate Zero-Copy Data-Sync Engine for Arduino
https://github.com/apadevices/apaserialsync
arduino arduino-library bi-directional cpp data-synchronization embedded microcontroller protocol serial serial-communication transfer uart-protocol
Last synced: about 9 hours ago
JSON representation
APASerialSync: The Ultimate Zero-Copy Data-Sync Engine for Arduino
- Host: GitHub
- URL: https://github.com/apadevices/apaserialsync
- Owner: apadevices
- License: mit
- Created: 2026-04-12T08:08:22.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T09:49:06.000Z (2 months ago)
- Last Synced: 2026-04-12T10:12:00.230Z (2 months ago)
- Topics: arduino, arduino-library, bi-directional, cpp, data-synchronization, embedded, microcontroller, protocol, serial, serial-communication, transfer, uart-protocol
- Language: C++
- Homepage: https://ais-dev-dvam5rizdrcefwneu2ingf-152136505447.europe-west2.run.app
- Size: 576 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# APASerialSync 🚀
**The Ultimate Zero-Copy Data-Sync Engine for Arduino**
Stop fighting with manual Serial parsing. **APASerialSync** is a high-performance, memory-thrifty library that makes synchronizing complex data structures between microcontrollers as easy as a single function call.
---
## 🌟 Why APASerialSync?
- 💎 **Zero-Copy Performance**: RAM is a luxury on 8-bit MCUs. Our architecture writes data directly into your variables, eliminating redundant internal buffers and maximizing efficiency.
- 🔄 **True Bi-Directional Sync**: Move data both ways simultaneously without complex state machines or blocking your code.
- 🌍 **MCU Agnostic**: Works seamlessly across AVR (Uno/Nano), ESP32, ESP8266, STM32, and more.
- ⚡ **Non-Blocking Logic**: No `delay()` calls. Your main loop stays fast and responsive.
- 🛡️ **Rock-Solid Reliability**: CRC16 checksums and Packet ID tracking ensure your data arrives 100% intact.
- 🧩 **Type-Safe Templates**: Uses C++ templates to handle any `struct` or `class` with full type safety.
---
## 🎨 The APA Serial-Sync Designer
Don't waste time writing boilerplate code by hand! We provide a powerful companion tool to help you get started:
1. **Online Version**: Use the **[Live Web Designer](https://ais-dev-dvam5rizdrcefwneu2ingf-152136505447.europe-west2.run.app)** to visually build your data structure and generate code.
2. **Local Version**: Check the `/DESIGNER` folder in this repository. It contains a ZIP file with the full designer tool that you can run locally on your machine (just open `index.html` in any browser).
---
## 🛠️ Installation
1. Download this repository as a `.zip` file.
2. In the Arduino IDE: **Sketch** -> **Include Library** -> **Add .ZIP Library...**
3. Select the downloaded file.
4. **Note**: If using `SoftwareSerial`, ensure you have it installed (usually built-in for AVR).
---
## 🔌 Wiring (The "Golden Rules")
To make the MCUs talk, you **must** follow these three rules:
1. **Cross the wires**: MCU1 **TX** goes to MCU2 **RX**. MCU1 **RX** goes to MCU2 **TX**.
2. **Common Ground**: Connect the **GND** pins of both MCUs together.
3. **Voltage Match**: If using a 5V MCU (Uno) with a 3.3V MCU (ESP32), use a logic level shifter.
---
## 📖 Quick Start
### 1. Define your Data
Both MCUs **must** use the exact same struct. We use `#pragma pack(push, 1)` to ensure the memory layout is identical on both sides.
```cpp
#pragma pack(push, 1)
struct MyData {
int counter;
float temperature;
bool ledStatus;
};
#pragma pack(pop)
```
### 2. Setup
Initialize the Serial port first, then the library.
```cpp
MyData myData;
// Pass the Serial port (e.g. Serial1) and your data variable
APASerialSync sync(Serial1, myData);
void setup() {
// 1. Start the Serial port at your desired speed
Serial1.begin(9600);
// 2. Initialize the library
sync.apaBegin();
}
```
### 3. The Loop
```cpp
void loop() {
// Check for incoming data (non-blocking)
if (sync.apaSync()) {
// 'myData' has been updated automatically!
digitalWrite(LED_BUILTIN, myData.ledStatus);
}
// Send local changes (e.g. every 2 seconds)
static unsigned long lastSend = 0;
if (millis() - lastSend > 2000) {
myData.counter++;
sync.apaSend();
lastSend = millis();
}
}
```
---
## 📂 Folder Structure
- `src/`: Library source code (`APASerialSync.h`).
- `examples/`: Organized samples (Basic, Intermediate, Advanced).
- `DESIGNER/`: Local version of the web-based code generator tool.
- `library.properties`: Arduino library metadata.
- `keywords.txt`: Syntax highlighting for Arduino IDE.
---
## ⚠️ Common Pitfalls
* **Forgot GND**: If grounds aren't connected, the signal has no reference and will fail.
* **Struct Mismatch**: If MCU1 has 4 variables and MCU2 has 3, the sync will fail CRC checks.
* **Blocking Code**: If your loop has long `delay()` calls, you might miss incoming serial data.
---
## ⚖️ License
Released under the **MIT License**. See [LICENSE](LICENSE) for details.