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
+121-6Lines changed: 121 additions & 6 deletions
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
@@ -125,20 +133,21 @@ This is usually done inside the `setup` function after the servo objects have be
125
133
Alternatively, we can also create an array of servos and call the `addServos` method instead:
126
134
127
135
```ino
136
+
Animation myBlenderAnimation(30, 1000);
137
+
128
138
Servo myBlenderServos[] = {
129
139
Servo(0, BoneA, move),
130
140
Servo(1, BoneB, move),
131
141
Servo(2, BoneC, move),
132
-
...
133
142
}
134
143
135
-
Animation myBlenderAnimation(30, 1000);
136
-
137
144
void setup() {
138
-
myBlenderAnimation.addServos(myBlenderServos);
145
+
myBlenderAnimation.addServos(myBlenderServos, 3);
139
146
}
140
147
```
141
148
149
+
> Note: the `addServos` function expects the amount of servos in the array to be passed via the second argument.
150
+
142
151
### Updating the Animation State
143
152
144
153
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`:
@@ -210,12 +219,118 @@ On top of manually checking the animation mode, we can also register a callback
210
219
211
220
```ino
212
221
voidmodeChanged(byte prevMode, byte newMode) {
213
-
// Do something (e.g. using another switch)
222
+
// Do something (e.g. using a switch statement)
214
223
}
215
224
216
225
void setup() {
217
226
myBlenderAnimation.onModeChange(modeChanged);
218
227
}
219
228
```
220
229
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.
230
+
The [SwitchModeButton example](examples/SwitchModeButton) shows how to combine all mode methods to control an animation based on a single button.
231
+
232
+
## Defining a Show
233
+
234
+
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:
235
+
236
+
```ino
237
+
Show myBlenderShow;
238
+
```
239
+
240
+
### Registering Animations
241
+
242
+
After defining some animations as shown above, we have to register them to the show object by calling the `addAnimation` method:
243
+
244
+
```ino
245
+
myBlenderShow.addAnimation(myBlenderAnimation);
246
+
```
247
+
248
+
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`).
249
+
250
+
Alternatively, we can also create an array of animations and call the `addAnimations` method instead:
251
+
252
+
```ino
253
+
Show myBlenderShow;
254
+
255
+
Animation animations[3] = {
256
+
{FPS, FRAMES_A},
257
+
{FPS, FRAMES_B},
258
+
{FPS, FRAMES_C},
259
+
};
260
+
261
+
voidsetup() {
262
+
myBlenderShow.addAnimations(animations, 3);
263
+
}
264
+
```
265
+
266
+
> Note: the `addAnimations` function expects the amount of servos in the array to be passed via the second argument.
267
+
268
+
### Updating the Show State
269
+
270
+
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`:
271
+
272
+
```ino
273
+
voidloop() {
274
+
myBlenderShow.run();
275
+
}
276
+
```
277
+
278
+
### Show Modes
279
+
280
+
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.
281
+
282
+
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:
283
+
284
+
| Constant | Method | Description |
285
+
|----------|--------|-------------|
286
+
| MODE_PLAY | play() | Start or resume playing the show once |
287
+
| MODE_PLAY_SINGLE | playSingle(index) | Start or resume playing a single animation once |
288
+
| MODE_PLAY_RANDOM | playRandom() | Start or resume randomly playing animations of the show |
289
+
290
+
The modes can be changed or triggered by calling the respective methods on the show object:
291
+
292
+
```ino
293
+
myBlenderShow.play();
294
+
myBlenderShow.playSingle(index);
295
+
myBlenderShow.playRandom();
296
+
myBlenderShow.pause();
297
+
myBlenderShow.loop();
298
+
myBlenderShow.stop();
299
+
myBlenderShow.live(stream);
300
+
```
301
+
302
+
> Note: the default mode can not be triggered as it is only handled internally.
303
+
304
+
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:
305
+
306
+
```ino
307
+
byte currentMode = myBlenderShow.getMode();
308
+
309
+
switch (currentMode) {
310
+
case Show::MODE_DEFAULT:
311
+
// Do something
312
+
break;
313
+
case Show::MODE_PLAY:
314
+
// Do something else
315
+
break;
316
+
...
317
+
}
318
+
```
319
+
320
+
> Note: The actual byte values of the show modes differ from the animation modes. For example, `Show::MODE_PAUSE != Animation::MODE_PAUSE`.
321
+
322
+
As with animations, we can also register an `onModeChange` callback function:
323
+
324
+
```ino
325
+
voidmodeChanged(byte prevMode, byte newMode) {
326
+
// Do something (e.g. using a switch statement)
327
+
}
328
+
329
+
void setup() {
330
+
myBlenderShow.onModeChange(modeChanged);
331
+
}
332
+
```
333
+
334
+
There is also a specific [Show example](examples/Show) to illustrate a simple setup based on 2 different animations.
335
+
336
+
Make sure to also check out the other [examples](examples) to get started more quickly.
0 commit comments