Exported Animations

Beginner Topic used frequently in Bottango workflows.

Big idea

Copy in the exported animation files and enable the module to turn on playing from exported animations.

When you export animations from the desktop app in “Save To Code” format, you will get two files per hardware driver: “GeneratedCodeAnimations.cpp” and “GeneratedCodeAnimations.h”

These files contain all the animation data, as well as the built-in playback triggering options you used when exporting.

Enabling exported animation playback

1. Drag both of those files into the root of the BottangoArduinoDriver folder. They contain all the data needed to play the animations, you will not need to make any changes to them. As well, they contain the playback configuration like which animation to play on startup if any, etc.

2. In BottangoArduinoModules.h, enable the ‘USE_CODE_COMMAND_STREAM’ module by removing the starting ”//”

   Remove the ”//” characters from the start of the line:

   BottangoArduinoModules.h

   // #define USE_CODE_COMMAND_STREAM      // uncomment this line to drive animations from exported code instead of live control

   so that it is enabled:

   BottangoArduinoModules.h

   #define USE_CODE_COMMAND_STREAM     // uncomment this line to drive animations from exported code instead of live control

3. Save your file changes, and reupload the firmware. As soon as the upload is complete, your playback triggering logic will begin evaluating right away.

4. To go back to live control, take the added files back out of the folder, put the ”//” back at the start of the line, and reupload again.

Custom Playback Triggering Logic

You are not limited to the built-in playback triggering logic. You can write your own code and create nearly any playback logic you’d like. This is discussed more in the Callbacks section of the documentation.

Exported Animation Limitations

When you export animations, you remove all the power and logic of the desktop app from your setup, and rely on the Bottango firmware to “run the show.” There are limitations to be aware of:

Microcontroller Memory Limits

When animations are exported, the size of the data is based on the number of keyframes, not the length of the animation. One animation with 10 total keyframes will take the same amount of space regardless of how long the animation is.

However, be aware of the limitations of how much space is available on your microcontroller. An Arduino Uno R3 usually has only around 10k of space left for animation storage after the driver itself is included. That could be only a minute or less of animation data, depending on how many keyframes.

An Arduino Mega has more memory available, but due to limitations on how the Mega works, only some of the storage space is accessible by the driver code. Only around 50k is available for animation storage on a Mega.

An ESP32 has in comparison far more memory available for animation storage. Out of the box, you’ll get around 500kb of space available. By changing the partition table on the ESP32 (Advanced but possible) you could access as much as 2.5mb of data on a standard ESP32.

SD Card Playback

As an advanced workflow, it’s possible to export animation files to be read from an SD card instead of embedded in the microcontroller’s memory. See the linked guide for more information. However, you’ll need to bring your own hardware, and support is limited to more advanced microcontrollers like an ESP32 or Teensy. Arduino Uno/Nano/Mega are not supported for SD card reading.

No Procedural Jogs

When animating on the desktop app, if you stop in the middle of animation A, and then start animation B, the desktop app will make a smooth procedural jog between the current motor positions from the middle of animation A to the desired new starting positions before beginning to play animation B. However, this functionality does not yet exist when the microcontroller is playing back animations from code.

When an animation is triggered by the microcontroller in exported animation mode, it begins playing right away. That means starting and stopping animations may result in sudden jumps. As well, transitioning from the end of animation A to the start of animation B may also result in sudden jumps. You can design around this by having each animation end and start with the same neutral pose.

There’s more advanced workarounds as well around acceleration planning and limits, but those are currently very experimental preview features.

However, with looping animations, there will be no sudden jump from the end of an animation back to its own beginning. When you export animation data, the app also exports a “loop” sequence to play at the end of the animation that will smoothly jog back to the beginning of the animation before starting again.

Effector Considerations

DYNAMIXEL effectors do not currently support exporting animations.

Stepper motors can have exported animations, however the homing/sync process with exported steppers is advanced.