|
1 | | -# PlatformIO Development Guide |
2 | | - |
3 | | -This document explains how to develop and test the ReactiveArduino library using PlatformIO. |
4 | | - |
5 | | -## Quick Start |
6 | | - |
7 | | -### Prerequisites |
8 | | -- [PlatformIO Core](https://platformio.org/install/cli) or [PlatformIO IDE](https://platformio.org/platformio-ide) |
9 | | -- Git |
10 | | - |
11 | | -### Setup |
12 | | -1. Clone the repository: |
13 | | - ```bash |
14 | | - git clone https://github.com/rzeldent/Arduino-ReactiveArduino.git |
15 | | - cd Arduino-ReactiveArduino |
16 | | - ``` |
17 | | - |
18 | | -2. Build for your target platform: |
19 | | - ```bash |
20 | | - # For Arduino Uno |
21 | | - pio run -e uno |
22 | | - |
23 | | - # For ESP32 |
24 | | - pio run -e esp32 |
25 | | - |
26 | | - # For ESP8266 |
27 | | - pio run -e esp8266 |
28 | | - ``` |
29 | | - |
30 | | -3. Upload to your device: |
31 | | - ```bash |
32 | | - pio run -e uno --target upload |
33 | | - ``` |
34 | | - |
35 | | -## Available Environments |
36 | | - |
37 | | -### Target Platforms |
38 | | -- `uno` - Arduino Uno |
39 | | -- `nano` - Arduino Nano |
40 | | -- `mega` - Arduino Mega 2560 |
41 | | -- `esp32` - ESP32 development board |
42 | | -- `esp8266` - ESP8266 (NodeMCU v2) |
43 | | -- `teensy` - Teensy 4.0 |
44 | | -- `due` - Arduino Due |
45 | | - |
46 | | -### Test Environments |
47 | | -- `test_blink` - Basic blink example |
48 | | -- `test_extensions` - New reactive extensions |
49 | | -- `test_pid` - PID controller example |
50 | | -- `test_distinct` - Distinct operator example |
51 | | -- `test_esp32_full` - Full feature test on ESP32 |
52 | | -- `lib_test` - Unit testing framework |
53 | | - |
54 | | -## Testing Examples |
55 | | - |
56 | | -### Build Specific Examples |
57 | | -```bash |
58 | | -# Test throttle example |
59 | | -pio run -e test_extensions |
60 | | - |
61 | | -# Test PID controller |
62 | | -pio run -e test_pid |
63 | | - |
64 | | -# Test distinct operator |
65 | | -pio run -e test_distinct |
66 | | -``` |
67 | | - |
68 | | -### Build All Examples |
69 | | -```bash |
70 | | -# Build all examples for ESP32 |
71 | | -pio ci --lib="." --board esp32dev examples/*/ |
72 | | - |
73 | | -# Build specific example for multiple boards |
74 | | -pio ci --lib="." --board uno --board esp32dev examples/Blink/Blink.cpp |
75 | | -``` |
76 | | - |
77 | | -## Development Workflow |
78 | | - |
79 | | -### 1. Code Changes |
80 | | -Make your changes to the library files in `src/` directory. |
81 | | - |
82 | | -### 2. Test Compilation |
83 | | -```bash |
84 | | -# Quick syntax check |
85 | | -pio run -e lib_test --target compiledb |
86 | | - |
87 | | -# Test on multiple platforms |
88 | | -pio run -e uno -e esp32 -e esp8266 |
89 | | -``` |
90 | | - |
91 | | -### 3. Test Examples |
92 | | -```bash |
93 | | -# Test all new extensions |
94 | | -pio run -e test_extensions |
95 | | -pio run -e test_pid |
96 | | -pio run -e test_distinct |
97 | | -``` |
98 | | - |
99 | | -### 4. Monitor Serial Output |
100 | | -```bash |
101 | | -# Upload and monitor |
102 | | -pio run -e esp32 --target upload --target monitor |
103 | | - |
104 | | -# Monitor existing upload |
105 | | -pio device monitor --port /dev/ttyUSB0 --baud 115200 |
106 | | -``` |
107 | | - |
108 | | -## New ReactiveArduino Extensions |
109 | | - |
110 | | -The library now includes these new reactive methods: |
111 | | - |
112 | | -### New Operators |
113 | | -- `Distinct()` - Remove all duplicate values |
114 | | -- `Throttle(ms)` - Rate limiting |
115 | | -- `Scan(seed, accumulator)` - Progressive accumulation |
116 | | -- `StartWith(value)` - Emit initial value |
117 | | -- `Debounce(ms)` - Advanced debouncing |
118 | | - |
119 | | -### New Filters |
120 | | -- `Hysteresis(low, high)` - Prevent oscillation |
121 | | -- `Kalman(process, measurement)` - Optimal noise filtering |
122 | | -- `PID(setpoint, kp, ki, kd)` - Complete PID controller |
123 | | - |
124 | | -### New Observables |
125 | | -- `AccelerometerInput()` - 3-axis motion sensing |
126 | | -- `UltrasonicSensor()` - Distance measurement |
127 | | -- `RotaryEncoder()` - Position tracking |
128 | | - |
129 | | -### New Transformations |
130 | | -- `Interpolate(inMin, inMax, outMin, outMax)` - Linear mapping |
131 | | - |
132 | | -## Memory Considerations |
133 | | - |
134 | | -### Arduino Uno/Nano (2KB RAM) |
135 | | -- Use basic operators and filters |
136 | | -- Avoid complex chaining |
137 | | -- Limit to 2-3 operators per chain |
138 | | - |
139 | | -### ESP32/ESP8266 (80KB+ RAM) |
140 | | -- Full feature support |
141 | | -- Complex operator chaining supported |
142 | | -- Advanced filtering and PID control |
143 | | - |
144 | | -### Optimization Tips |
145 | | -- Use `REACTIVE_EXTENDED_MEMORY` flag for more features |
146 | | -- Prefer stack allocation over dynamic allocation |
147 | | -- Monitor memory usage with `pio run --target size` |
148 | | - |
149 | | -## Continuous Integration |
150 | | - |
151 | | -The project uses GitHub Actions for automated testing: |
152 | | - |
153 | | -- **Build Examples**: Tests all examples on multiple platforms |
154 | | -- **Library Test**: Validates library compilation |
155 | | -- **Syntax Check**: Ensures code quality |
156 | | - |
157 | | -### Local CI Testing |
158 | | -```bash |
159 | | -# Simulate CI locally |
160 | | -pio ci --lib="." --board uno --board esp32dev examples/Blink/Blink.cpp |
161 | | -pio ci --lib="." --board esp32dev src/main.cpp |
162 | | -``` |
163 | | - |
164 | | -## Troubleshooting |
165 | | - |
166 | | -### Common Issues |
167 | | - |
168 | | -1. **Memory Errors on Arduino Uno** |
169 | | - - Solution: Use simpler examples or switch to ESP32 |
170 | | - - Alternative: Enable memory optimization flags |
171 | | - |
172 | | -2. **Compilation Errors** |
173 | | - - Check include paths in `platformio.ini` |
174 | | - - Verify all header files are properly included |
175 | | - - Run `pio run --target clean` and rebuild |
176 | | - |
177 | | -3. **Upload Failures** |
178 | | - - Check device connection and port |
179 | | - - Verify correct board selection |
180 | | - - Try different upload speeds |
181 | | - |
182 | | -### Debug Tips |
183 | | -```bash |
184 | | -# Verbose compilation |
185 | | -pio run -e uno --verbose |
186 | | - |
187 | | -# Check library dependencies |
188 | | -pio lib deps |
189 | | - |
190 | | -# Clean build |
191 | | -pio run --target clean |
192 | | -``` |
193 | | - |
194 | | -## Contributing |
195 | | - |
196 | | -1. Fork the repository |
197 | | -2. Create a feature branch |
198 | | -3. Make your changes |
199 | | -4. Test on multiple platforms using PlatformIO |
200 | | -5. Submit a pull request |
201 | | - |
202 | | -The CI will automatically test your changes on all supported platforms. |
0 commit comments