|
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