You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+127-13
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,8 @@
2
2
3
3
This library helps to control servos based on an exported Blender animation. It is specifically designed to work with the [Blender Servo Animation Add-on](https://github.com/timhendriks93/blender-servo-animation).
Please refer to the official [Arduino documentation](https://docs.arduino.cc/software/ide-v1/tutorials/installing-libraries) to see how you can install this library.
When not using the standard servo library, you can use the namespace and therefore skip the namespace prefix:
@@ -39,6 +44,9 @@ Servo(...);
39
44
40
45
// Blender animation object
41
46
Animation(...);
47
+
48
+
// Blender show object
49
+
Show();
42
50
```
43
51
44
52
## Defining Servos
@@ -61,7 +69,9 @@ Servo(id, callback, threshold);
61
69
| id | byte | Unique servo ID as specified via the Add-on |
62
70
| positions | const int[] | Exported positions per frame |
63
71
| callback | void (byte, int) | Function to trigger when a servo is moved |
64
-
| threshold | byte | Max allowed position diff (default=20) |
72
+
| threshold | byte | Max allowed position diff (default=0 / no threshold handling) |
73
+
74
+
> Note: the threshold is also used to define the speed for moving a servo to its neutral position when stopping an animation.
65
75
66
76
### Callback Function
67
77
@@ -125,20 +135,21 @@ This is usually done inside the `setup` function after the servo objects have be
125
135
Alternatively, we can also create an array of servos and call the `addServos` method instead:
126
136
127
137
```ino
138
+
Animation myBlenderAnimation(30, 1000);
139
+
128
140
Servo myBlenderServos[] = {
129
141
Servo(0, BoneA, move),
130
142
Servo(1, BoneB, move),
131
143
Servo(2, BoneC, move),
132
-
...
133
144
}
134
145
135
-
Animation myBlenderAnimation(30, 1000);
136
-
137
146
void setup() {
138
-
myBlenderAnimation.addServos(myBlenderServos);
147
+
myBlenderAnimation.addServos(myBlenderServos, 3);
139
148
}
140
149
```
141
150
151
+
> Note: the `addServos` function expects the amount of servos in the array to be passed via the second argument.
152
+
142
153
### Updating the Animation State
143
154
144
155
The animation needs to be triggered regularly in order to update its state and check if any servos have to be moved. We therefore need to call the `run` method during each `loop`:
> Note: the default mode can not be triggered as it is only handled internally.
176
187
177
-
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`.
myBlenderAnimation.stop(30); // Servos will reset slower
182
-
```
188
+
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.
183
189
184
190
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:
185
191
@@ -190,6 +196,8 @@ void setup() {
190
196
}
191
197
```
192
198
199
+
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).
200
+
193
201
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:
194
202
195
203
```ino
@@ -210,12 +218,118 @@ On top of manually checking the animation mode, we can also register a callback
210
218
211
219
```ino
212
220
voidmodeChanged(byte prevMode, byte newMode) {
213
-
// Do something (e.g. using another switch)
221
+
// Do something (e.g. using a switch statement)
214
222
}
215
223
216
224
void setup() {
217
225
myBlenderAnimation.onModeChange(modeChanged);
218
226
}
219
227
```
220
228
221
-
The [SwitchModeButton example](examples/SwitchModeButton) shows how to combine all mode methods to control an animation based on a single button. Make sure to also check out the other [examples](examples) to get started quickly.
229
+
The [SwitchModeButton example](examples/SwitchModeButton) shows how to combine all mode methods to control an animation based on a single button.
230
+
231
+
## Defining a Show
232
+
233
+
A show object allows you to combine multiple animations and control their play back in an easy way. You can also think of a show as a playlist of animations. Since the show object does not expect any arguments, the initialization is very simple:
234
+
235
+
```ino
236
+
Show myBlenderShow;
237
+
```
238
+
239
+
### Registering Animations
240
+
241
+
After defining some animations as shown above, we have to register them to the show object by calling the `addAnimation` method:
242
+
243
+
```ino
244
+
myBlenderShow.addAnimation(myBlenderAnimation);
245
+
```
246
+
247
+
This is usually done inside the `setup` function after the animation and servo objects have been defined globally (outside of any function like `setup` or `loop`).
248
+
249
+
Alternatively, we can also create an array of animations and call the `addAnimations` method instead:
250
+
251
+
```ino
252
+
Show myBlenderShow;
253
+
254
+
Animation animations[3] = {
255
+
{FPS, FRAMES_A},
256
+
{FPS, FRAMES_B},
257
+
{FPS, FRAMES_C},
258
+
};
259
+
260
+
voidsetup() {
261
+
myBlenderShow.addAnimations(animations, 3);
262
+
}
263
+
```
264
+
265
+
> Note: the `addAnimations` function expects the amount of servos in the array to be passed via the second argument.
266
+
267
+
### Updating the Show State
268
+
269
+
Just like single animations, we have to regularly trigger the show instance in order to update its state and internally handle the servo movement of the current animation. We therefore need to call the `run` method during each `loop`:
270
+
271
+
```ino
272
+
voidloop() {
273
+
myBlenderShow.run();
274
+
}
275
+
```
276
+
277
+
### Show Modes
278
+
279
+
The show modes are similar to the previously mentioned animation modes. In addition to those, there are various playback modes to handle a multitude of animations.
280
+
281
+
Just like with animation modes, a show will be in the default mode at first. The following table is focusing on the differences and additions of the show modes compared to the animation modes:
282
+
283
+
| Constant | Method | Description |
284
+
|----------|--------|-------------|
285
+
| MODE_PLAY | play() | Start or resume playing the show once |
286
+
| MODE_PLAY_SINGLE | playSingle(index) | Start or resume playing a single animation once |
287
+
| MODE_PLAY_RANDOM | playRandom() | Start or resume randomly playing animations of the show |
288
+
289
+
The modes can be changed or triggered by calling the respective methods on the show object:
290
+
291
+
```ino
292
+
myBlenderShow.play();
293
+
myBlenderShow.playSingle(index);
294
+
myBlenderShow.playRandom();
295
+
myBlenderShow.pause();
296
+
myBlenderShow.loop();
297
+
myBlenderShow.stop();
298
+
myBlenderShow.live(stream);
299
+
```
300
+
301
+
> Note: the default mode can not be triggered as it is only handled internally.
302
+
303
+
To get the current show mode, we can again call a `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:
304
+
305
+
```ino
306
+
byte currentMode = myBlenderShow.getMode();
307
+
308
+
switch (currentMode) {
309
+
case Show::MODE_DEFAULT:
310
+
// Do something
311
+
break;
312
+
case Show::MODE_PLAY:
313
+
// Do something else
314
+
break;
315
+
...
316
+
}
317
+
```
318
+
319
+
> Note: The actual byte values of the show modes differ from the animation modes. For example, `Show::MODE_PAUSE != Animation::MODE_PAUSE`.
320
+
321
+
As with animations, we can also register an `onModeChange` callback function:
322
+
323
+
```ino
324
+
voidmodeChanged(byte prevMode, byte newMode) {
325
+
// Do something (e.g. using a switch statement)
326
+
}
327
+
328
+
void setup() {
329
+
myBlenderShow.onModeChange(modeChanged);
330
+
}
331
+
```
332
+
333
+
There is also a specific [Show example](examples/Show) to illustrate a simple setup based on 2 different animations.
334
+
335
+
Make sure to also check out the other [examples](examples) to get started more quickly.
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.
4
+
5
+
0 commit comments