Merge branch 'feature/web_socket_live_mode' into develop

Author: timhendriks93

.github/workflows/ci.yml

@@ -23,11 +23,13 @@ jobs:
     name: "Build examples"
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         example:
           [
             AdafruitPCA9685,
-            LiveMode,
+            SerialLiveMode,
+            WebSocketLiveMode,
             MultiplePCA9685,
             Show,
             StandardServoLib,
@@ -48,9 +50,8 @@ jobs:
         run: pip install --upgrade platformio
       - name: Build PlatformIO examples
         run: |
-          pio ci examples/${{ matrix.example }} \
-            --lib=. \
-            --project-conf=examples/${{ matrix.example }}/platformio.ini
+          cd examples/${{ matrix.example }}
+          pio run
   lint:
     name: "Lint"
     runs-on: ubuntu-22.04

.gitignore

@@ -3,3 +3,5 @@
 .vscode/c_cpp_properties.json
 .vscode/launch.json
 .vscode/ipch
+examples/*/.vscode
+examples/*/.gitignore

README.md

@@ -69,7 +69,9 @@ Servo(id, callback, threshold);
 | id | byte | Unique servo ID as specified via the Add-on |
 | positions | const int[] | Exported positions per frame |
 | callback | void (byte, int) | Function to trigger when a servo is moved |
-| threshold | byte | Max allowed position diff (default=20) |
+| threshold | byte | Max allowed position diff (default=0 / no threshold handling) |
+
+> Note: the threshold is also used to define the speed for moving a servo to its neutral position when stopping an animation.
 
 ### Callback Function
 
@@ -183,12 +185,7 @@ myBlenderAnimation.live(stream);
 
 > Note: the default mode can not be triggered as it is only handled internally.
 
-When calling the `stop` method, it is possible to pass a delay in milliseconds. This delay will be used when the servos are moved to their neutral position during the stop mode. To get to the neutral position, the current position will either be increased or decreased by 1. The delay therefore controls how fast or smooth this movement will take place. The default value for this parameter is `20`.
-
-```ino
-myBlenderAnimation.stop(); // Default reset speed applied
-myBlenderAnimation.stop(30); // Servos will reset slower
-```
+When calling the `stop` method, the threshold values of the animation's servos are considered to control how fast or smooth they are moving towards their neutral position. Keep in mind that the servos will not have a threshold value by default which results in the stop mode to immediately trigger the neutral position of the servos. A slower and safer movement can be achieved by setting the threshold values as low as possible with the actual animation still able to run properly.
 
 To use the `live` method, we have to pass a stream instance which will be used for reading serial commands. For example, we can pass `Serial` if we want to use the standard USB connection of an Arduino compatible board:
 
@@ -199,6 +196,8 @@ void setup() {
 }
 ```
 
+This library also comes with a `LiveStream` class which allows for a more generic way to listen to live commands. For example, it can be used as part of the web socket based live mode for which you can find a dedicated example [here](examples/WebSocketLiveMode).
+
 To get the current animation mode, we can simply call the `getMode` method. This will return a `byte` representing one of the mode constants mentioned in the table above. We can then compare the return value to those constants to act according to the current mode:
 
 ```ino

examples/AdafruitPCA9685/AdafruitPCA9685.ino

@@ -13,12 +13,6 @@
 // Using the namespace to have short class references (Animation and Servo)
 using namespace BlenderServoAnimation;
 
-// Frames per second - see original Blender animation / ik.h
-#define FPS 30
-
-// Total animation frames - see original Blender animation / ik.h
-#define FRAMES 100
-
 // PWM driver instance to set PWM output
 Adafruit_PWMServoDriver pwm = Adafruit_PWMServoDriver();
 

examples/AdafruitPCA9685/README.md

@@ -0,0 +1,5 @@
+# Adafruit PCA9685
+
+Using a PCA9685 PWM Servo Driver to animate 2 servos. The animation is based on the IK example of the Blender Servo Animation add-on which resembles a simple neck mechanism.
+
+![test](../../images/arduino-nano-with-PCA9685.png)

examples/AdafruitPCA9685/ik.h

@@ -6,19 +6,23 @@
   Seconds: 3
   Bones: 2
   Armature: Armature
+  Scene: Scene
   File: ik.blend
 */
 
 #include <Arduino.h>
 
+const byte FPS = 30;
+const int FRAMES = 100;
+
 // Servo ID: 0
-const int NeckLeft[100] PROGMEM = {
+const int NeckLeft[FRAMES] PROGMEM = {
   375, 376, 377, 380, 384, 387, 391, 396, 400, 403, 406, 408, 410, 410, 409, 406, 402, 396, 390, 382, 373, 364, 355, 346, 338, 330, 323, 318, 314, 311, 309, 307, 305, 305, 305, 305, 306, 307, 309, 311, 314, 317, 320, 323, 327, 331, 335, 339, 343, 347,
   351, 356, 360, 364, 369, 374, 380, 386, 392, 398, 404, 410, 415, 420, 425, 429, 432, 435, 436, 437, 437, 436, 435, 434, 432, 430, 428, 426, 423, 421, 418, 415, 412, 409, 406, 403, 400, 397, 394, 391, 388, 386, 384, 381, 380, 378, 377, 376, 375, 375,
 };
 
 // Servo ID: 1
-const int NeckRight[100] PROGMEM = {
+const int NeckRight[FRAMES] PROGMEM = {
   375, 376, 379, 383, 388, 394, 401, 409, 417, 426, 434, 443, 450, 457, 463, 468, 471, 472, 471, 469, 466, 462, 457, 452, 447, 441, 437, 432, 428, 424, 420, 416, 411, 407, 402, 398, 394, 389, 384, 380, 375, 370, 366, 361, 356, 352, 347, 342, 337, 333,
   328, 324, 319, 315, 312, 309, 308, 307, 306, 306, 306, 307, 308, 309, 310, 311, 312, 313, 313, 313, 313, 314, 315, 316, 318, 320, 322, 324, 327, 329, 332, 335, 338, 341, 344, 347, 350, 353, 356, 359, 362, 364, 366, 369, 370, 372, 373, 374, 375, 375,
 };

examples/AdafruitPCA9685/platformio.ini

@@ -1,6 +1,10 @@
+[platformio]
+src_dir = ./
+
 [env]
 lib_deps = 
 	adafruit/Adafruit PWM Servo Driver Library@^2.4.1
+	BlenderServoAnimation=symlink://../../
 
 [env:uno]
 board = uno

examples/LiveMode/platformio.ini

@@ -13,12 +13,6 @@
 // Using the namespace to have short class references (Animation and Servo)
 using namespace BlenderServoAnimation;
 
-// Frames per second - see original Blender animation / ik.h
-#define FPS 30
-
-// Total animation frames - see original Blender animation / ik.h
-#define FRAMES 100
-
 // PWM driver instances to set PWM output
 Adafruit_PWMServoDriver pwmA(0x40);
 Adafruit_PWMServoDriver pwmB(0x41);
@@ -36,12 +30,12 @@ struct servoMap {
 // Forward declare the callback as it will be referenced in the following array
 void setPWM(byte servoID, int position);
 
-// Define an array of servo maps
+// Define an array of servo mapsf
 servoMap servoMaps[] = {
     // Servo attached to board A on channel 0
     {Servo(0, NeckLeft, setPWM), pwmA, 0},
 
-    // Servo attached to board A on channel 0
+    // Servo attached to board B on channel 0
     {Servo(1, NeckRight, setPWM), pwmB, 0},
 };
 

examples/MultiplePCA9685/MultiplePCA9685.ino

@@ -0,0 +1,7 @@
+# Multiple PCA9685
+
+Using two PCA9685 PWM Servo Drivers to animate 2 servos. The animation is based on the IK example of the Blender Servo Animation add-on which resembles a simple neck mechanism.
+
+Note that the A0 address jumper has to be soldered on the second driver board. This setup can easily be extended to animate up to 32 servos. If even more servos are needed, you can also add more driver boards to the chain.
+
+![test](../../images/arduino-nano-with-2-PCA9685.png)

examples/MultiplePCA9685/README.md

@@ -6,19 +6,23 @@
   Seconds: 3
   Bones: 2
   Armature: Armature
+  Scene: Scene
   File: ik.blend
 */
 
 #include <Arduino.h>
 
+const byte FPS = 30;
+const int FRAMES = 100;
+
 // Servo ID: 0
-const int NeckLeft[100] PROGMEM = {
+const int NeckLeft[FRAMES] PROGMEM = {
   375, 376, 377, 380, 384, 387, 391, 396, 400, 403, 406, 408, 410, 410, 409, 406, 402, 396, 390, 382, 373, 364, 355, 346, 338, 330, 323, 318, 314, 311, 309, 307, 305, 305, 305, 305, 306, 307, 309, 311, 314, 317, 320, 323, 327, 331, 335, 339, 343, 347,
   351, 356, 360, 364, 369, 374, 380, 386, 392, 398, 404, 410, 415, 420, 425, 429, 432, 435, 436, 437, 437, 436, 435, 434, 432, 430, 428, 426, 423, 421, 418, 415, 412, 409, 406, 403, 400, 397, 394, 391, 388, 386, 384, 381, 380, 378, 377, 376, 375, 375,
 };
 
 // Servo ID: 1
-const int NeckRight[100] PROGMEM = {
+const int NeckRight[FRAMES] PROGMEM = {
   375, 376, 379, 383, 388, 394, 401, 409, 417, 426, 434, 443, 450, 457, 463, 468, 471, 472, 471, 469, 466, 462, 457, 452, 447, 441, 437, 432, 428, 424, 420, 416, 411, 407, 402, 398, 394, 389, 384, 380, 375, 370, 366, 361, 356, 352, 347, 342, 337, 333,
   328, 324, 319, 315, 312, 309, 308, 307, 306, 306, 306, 307, 308, 309, 310, 311, 312, 313, 313, 313, 313, 314, 315, 316, 318, 320, 322, 324, 327, 329, 332, 335, 338, 341, 344, 347, 350, 353, 356, 359, 362, 364, 366, 369, 370, 372, 373, 374, 375, 375,
 };

examples/MultiplePCA9685/ik.h

@@ -1,6 +1,10 @@
+[platformio]
+src_dir = ./
+
 [env]
 lib_deps = 
 	adafruit/Adafruit PWM Servo Driver Library@^2.4.1
+	BlenderServoAnimation=symlink://../../
 
 [env:uno]
 board = uno

examples/MultiplePCA9685/platformio.ini

@@ -0,0 +1,7 @@
+# Serial Live Mode
+
+Sending live servo positions via serial commands.
+
+This example requires a USB connection to your PC and a running Blender instance with the Blender Servo Animation Add-on. After starting the live mode by connecting to the micro controller via serial, you can move the servo in real time via Blender.
+
+![test](../../images/arduino-nano-with-servo.png)

examples/SerialLiveMode/README.md

@@ -7,15 +7,20 @@
 */
 
 #include <BlenderServoAnimation.h>
+
+#ifdef ARDUINO_ARCH_ESP32
+#include <ESP32Servo.h>
+#else
 #include <Servo.h>
+#endif
 
 // Servo object to send positions
 Servo myServo;
 
 // Callback function which is called whenever a servo needs to be moved
-void move(byte servoID, int angle) {
-  // Ignore the servoID (there is only one servo) and write the current angle
-  myServo.write(angle);
+void move(byte servoID, int position) {
+  // Ignore the servoID (there is only one servo) and write the current position
+  myServo.writeMicroseconds(position);
 }
 
 // Animation object to manage the servos
@@ -28,8 +33,8 @@ BlenderServoAnimation::Servo myBlenderServo(0, move);
 void setup() {
   Serial.begin(115200);
 
-  // Attach the servo to pin 9
-  myServo.attach(9);
+  // Attach the servo to pin 12
+  myServo.attach(12);
 
   // Add the Blender servo object to the animation
   animation.addServo(myBlenderServo);

examples/LiveMode/LiveMode.ino renamed to examples/SerialLiveMode/SerialLiveMode.ino

@@ -0,0 +1,30 @@
+[platformio]
+src_dir = ./
+
+[env]
+framework = arduino
+
+[atmelavr_base]
+platform = atmelavr
+lib_deps = 
+	arduino-libraries/Servo@^1.1.8
+	BlenderServoAnimation=symlink://../../
+
+[env:uno]
+extends = atmelavr_base
+board = uno
+
+[env:ATmega2560]
+extends = atmelavr_base
+board = ATmega2560
+
+[env:nanoatmega328]
+extends = atmelavr_base
+board = nanoatmega328
+
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+lib_deps = 
+	madhephaestus/ESP32Servo@^0.13.0
+	BlenderServoAnimation=symlink://../../

examples/SerialLiveMode/platformio.ini

@@ -0,0 +1,7 @@
+# Show
+
+Setting up a show consisting of 2 animations.
+
+By default, the 2 animations will be played synchronously in a loop.
+
+![test](../../images/arduino-nano-with-servo.png)

examples/Show/README.md

@@ -9,15 +9,20 @@
 #include "scene-a.h"
 #include "scene-b.h"
 #include <BlenderServoAnimation.h>
+
+#ifdef ARDUINO_ARCH_ESP32
+#include <ESP32Servo.h>
+#else
 #include <Servo.h>
+#endif
 
 // Servo object to send positions
 Servo myServo;
 
 // Callback function which is called whenever a servo needs to be moved
-void move(byte servoID, int angle) {
-  // Ignore the servoID (there is only one servo) and write the current angle
-  myServo.write(angle);
+void move(byte servoID, int position) {
+  // Ignore the servoID (there is only one servo) and write the current position
+  myServo.writeMicroseconds(position);
 }
 
 // Show object to manage all Blender animations
@@ -32,8 +37,8 @@ BlenderServoAnimation::Servo myBlenderServoA(0, SceneA::Bone, move);
 BlenderServoAnimation::Servo myBlenderServoB(0, SceneB::Bone, move);
 
 void setup() {
-  // Attach the servo to pin 9
-  myServo.attach(9);
+  // Attach the servo to pin 12
+  myServo.attach(12);
 
   // Add the Blender servo objects to the animations
   animationA.addServo(myBlenderServoA);

examples/Show/Show.ino

@@ -1,18 +1,30 @@
+[platformio]
+src_dir = ./
+
 [env]
+framework = arduino
+
+[atmelavr_base]
+platform = atmelavr
 lib_deps = 
 	arduino-libraries/Servo@^1.1.8
+	BlenderServoAnimation=symlink://../../
 
 [env:uno]
+extends = atmelavr_base
 board = uno
-platform = atmelavr
-framework = arduino
 
 [env:ATmega2560]
+extends = atmelavr_base
 board = ATmega2560
-platform = atmelavr
-framework = arduino
 
 [env:nanoatmega328]
+extends = atmelavr_base
 board = nanoatmega328
-platform = atmelavr
-framework = arduino
+
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+lib_deps = 
+	madhephaestus/ESP32Servo@^0.13.0
+	BlenderServoAnimation=symlink://../../

examples/Show/platformio.ini

@@ -19,8 +19,8 @@ const int FRAMES = 100;
 
 // Servo ID: 0
 const int Bone[FRAMES] PROGMEM = {
-  90, 90, 89, 89, 88, 87, 86, 84, 83, 81, 80, 78, 76, 74, 72, 70, 68, 65, 63, 61, 59, 57, 55, 54, 52, 51, 49, 48, 47, 46, 46, 45, 45, 45, 46, 47, 49, 51, 53, 55, 58, 61, 65, 68, 72, 76, 80, 84, 88, 92,
-  96, 100, 104, 108, 112, 115, 119, 122, 125, 127, 129, 131, 133, 134, 135, 135, 135, 135, 134, 133, 132, 131, 130, 129, 127, 126, 124, 122, 120, 118, 116, 114, 112, 111, 109, 107, 105, 103, 101, 99, 98, 96, 95, 94, 93, 92, 91, 90, 90, 90,
+  1472, 1473, 1477, 1483, 1492, 1502, 1515, 1529, 1544, 1562, 1580, 1599, 1619, 1640, 1661, 1682, 1704, 1726, 1747, 1768, 1789, 1809, 1828, 1846, 1864, 1879, 1893, 1906, 1916, 1925, 1931, 1935, 1936, 1934, 1926, 1914, 1898, 1879, 1855, 1828, 1799, 1767, 1732, 1695, 1657, 1617, 1577, 1535, 1493, 1451,
+  1409, 1367, 1327, 1287, 1249, 1212, 1177, 1145, 1116, 1089, 1065, 1046, 1030, 1018, 1010, 1008, 1009, 1013, 1018, 1026, 1035, 1046, 1059, 1073, 1088, 1105, 1122, 1141, 1160, 1179, 1199, 1220, 1240, 1260, 1281, 1301, 1320, 1339, 1358, 1375, 1392, 1407, 1421, 1434, 1445, 1454, 1462, 1467, 1471, 1472,
 };
 
 } // namespace SceneA

examples/Show/scene-a.h

@@ -19,10 +19,10 @@ const int FRAMES = 200;
 
 // Servo ID: 0
 const int Bone[FRAMES] PROGMEM = {
-  90, 90, 90, 90, 90, 90, 90, 89, 89, 89, 89, 88, 88, 88, 88, 87, 87, 86, 86, 86, 85, 85, 84, 84, 83, 83, 82, 82, 81, 81, 80, 80, 79, 78, 78, 77, 76, 76, 75, 75, 74, 73, 73, 72, 71, 71, 70, 69, 69, 68,
-  67, 66, 66, 65, 64, 64, 63, 62, 62, 61, 60, 60, 59, 59, 58, 57, 57, 56, 55, 55, 54, 54, 53, 53, 52, 52, 51, 51, 50, 50, 49, 49, 49, 48, 48, 47, 47, 47, 47, 46, 46, 46, 46, 45, 45, 45, 45, 45, 45, 45,
-  45, 45, 45, 45, 45, 45, 46, 46, 46, 46, 47, 47, 47, 47, 48, 48, 48, 49, 49, 50, 50, 51, 51, 52, 52, 53, 53, 54, 54, 55, 55, 56, 56, 57, 58, 58, 59, 60, 60, 61, 61, 62, 63, 63, 64, 65, 65, 66, 67, 68,
-  68, 69, 70, 70, 71, 72, 72, 73, 74, 74, 75, 75, 76, 77, 77, 78, 79, 79, 80, 80, 81, 81, 82, 82, 83, 83, 84, 84, 85, 85, 86, 86, 87, 87, 87, 88, 88, 88, 88, 89, 89, 89, 89, 90, 90, 90, 90, 90, 90, 90,
+  1472, 1472, 1473, 1473, 1474, 1475, 1477, 1479, 1481, 1483, 1485, 1488, 1491, 1494, 1497, 1501, 1504, 1508, 1512, 1517, 1521, 1526, 1531, 1536, 1541, 1546, 1551, 1557, 1562, 1568, 1574, 1580, 1586, 1592, 1599, 1605, 1611, 1618, 1625, 1631, 1638, 1645, 1652, 1659, 1666, 1672, 1679, 1686, 1693, 1700,
+  1708, 1715, 1722, 1729, 1736, 1742, 1749, 1756, 1763, 1770, 1777, 1783, 1790, 1797, 1803, 1809, 1816, 1822, 1828, 1834, 1840, 1846, 1851, 1857, 1862, 1867, 1872, 1877, 1882, 1887, 1891, 1896, 1900, 1904, 1907, 1911, 1914, 1917, 1920, 1923, 1925, 1927, 1929, 1931, 1933, 1934, 1935, 1935, 1936, 1936,
+  1936, 1935, 1935, 1934, 1933, 1931, 1930, 1928, 1925, 1923, 1920, 1918, 1915, 1911, 1908, 1904, 1900, 1896, 1892, 1888, 1883, 1878, 1874, 1869, 1864, 1858, 1853, 1847, 1842, 1836, 1830, 1824, 1818, 1812, 1805, 1799, 1792, 1786, 1779, 1773, 1766, 1759, 1752, 1746, 1739, 1732, 1725, 1718, 1711, 1704,
+  1697, 1690, 1683, 1676, 1669, 1662, 1656, 1649, 1642, 1635, 1629, 1622, 1616, 1609, 1603, 1596, 1590, 1584, 1578, 1572, 1566, 1561, 1555, 1550, 1544, 1539, 1534, 1530, 1525, 1520, 1516, 1512, 1508, 1504, 1500, 1497, 1493, 1490, 1488, 1485, 1483, 1480, 1478, 1477, 1475, 1474, 1473, 1473, 1472, 1472,
 };
 
 } // namespace SceneB