Configuration File

Expert Topic for experienced builders.

Bottango provides a centralized place for developer constants and advanced configurations in the BottangoArduinoConfig.h file. Though in most use cases you will not change the values in this file, there are times you may need to make changes.

Not every constant is covered in this guide, only the ones most likely to be tweaked. You can refer to the file itself for an explination of all values.

Max Registered Effectors

#if defined(ARDUINO_AVR_UNO) || defined(ARDUINO_AVR_NANO)
#ifdef USE_ADAFRUIT_PWM_LIBRARY
#define MAX_REGISTERED_EFFECTORS 6 // Arduino Uno or Nano + PCA driver can only support 6
#else
#define MAX_REGISTERED_EFFECTORS 8 // Arduino Uno or Nano bare pin pwm supports 8
#endif
#else
#define MAX_REGISTERED_EFFECTORS 16 // most modern boards can handle 16 or more (EX, ESP32, etc.)
#endif

To constrain resource usages, especially in low RAM microcontrollers like an Arduino Uno, there is a cap on the maximum number of effectors able to be registered. Servos, steppers, custom events, audio events, all animatable elements each take up one slot.

For a microcontroller with resources and RAM to spare (like an ESP32) you can increase this number beyond the default 16 if needed without much issue.

An Arduino Uno can handle 8 maximum effectors (5 if using a PCA9685 servo driver). Increasing this number on an Arduino Uno will not allow you to drive more effectors, it will just result in you encountering an out of memory crash instead of the max effector capped reached warning.

Module Pins

Many advanced modules require the firmware to know which GPIO pins to use to enable the functionality. For example, if you added an SD card reader to your development board and enabled the SD card reading module the firmware needs to know which pins are wired for MISO, MOSI, CLK, and CS.

If you are enabling a module, and you need to tell the firmware which pins to use, the place to put it will invariably be the BottangoArduinoConfig.h file.

Curve Interpolation Math

#define DEFAULT_FLOAT_CURVE // float math option (default, battle hardened and highly tested)
// #define DEFAULT_FIXED_CURVE                      // fixed math option. Slightly lower curve precision, but faster.  Likely will see improved HW communication and higher max effector count. New and being tested.

The firmware evaluated bezier curves when playing animations, and can use either floating point or fixed math to evaluate. You can choose either. Fixed math curve evaluation is generally more efficient without any meaningful loss in accuracy. Floating point evaluation is the default currently, but fixed math will become the default in a future version.

Stepper Motor Configuration

#define VELOCITY_SEGMENT_MS 67                      // Velocity effectors (IE steppers) will segment curves into chunks of velocity. This field defines how long each chunk is in MS.
                                                    // lower number means more segments. More segments will be more accurate to the curve, but slower to process and less smooth stepper movement
                                                    // If you wanted to target 15 segments per second (the default) divide 1000 by 15: 1000 / 15 = 66.666, so rounded to 67
                                                    // 30 segments per second would be 33, etc.

#define STEPPER_SYNC_SPEED 2                        // steppers will sync at 1/X percent of max speed. IE, 2 == 50% max speed, 4 == 25% max Speed, etc.

In order to keep a steady feed rate on stepper motors, the firmware chunks bezier curves into segments of equal length to reduce jitter and improve stepper performance. Without this optimization, since step rate is driven on the main loop instead of in an interrupt or task, any loop timing jitter would be reflected in the performance of the stepper itself. VELOCITY_SEGMENT_MS sets the size of the chunks in milliseconds. Smaller values will be more accurate to the curve in theory, but will increase the amount of jitter. Larger values will be less accurate to the curve, approaching unwanted smoothing if you take the value too high, but will reduce jitter even more.

When homing a stepper, it moves towards the desired position at a stead rate. STEPPER_SYNC_SPEED defines that speed, as a 1/X ratio of the maximum speed of the given stepper. At the default value of 2, steppers will move at 50% their max speed when homing.

Additional Configurations

#define BAUD_RATE 115200                                     // serial speed at which Bottango and Arduino communicate with each other

You can adjust the serial baud rate, but be sure to adjust the baud rate in the driver settings of your project file as well to match.

#define TRIGGER_EVENT_PIN_TIME 250                            // time in MS to keep a pin high before setting it back low in trigger events

You can adjust how long to take a pin HIGH/LOW when driven by a trigger event that sets a hardware pin, in milliseconds.

#define MAX_EXPORTED_ANIMATIONS 32                          // max number of animations that can be exported and played back without PC connection

By default, you can have at most 32 exported animations. The number can be increased if needed.

Additional Logging

While troubleshooting, it may be helpful to enable additional logging.

#define EXPORTED_ANIM_LOGGING                               // extra logging of status of exported animation playback
// #define RELAY_LOGGING                                    // extra logging of relay status
#define RELAY_COMMS_LOGGING                              // extra logging of relay comms state machines (RS485, etc)
// #define RELAY_COMMS_LOGGING_DEBUG                       // extra verbose relay comms logging (payloads, state traces)
// #define ESP32WIFI_LOGGING                                   // when communicating without serial, enable it for extra logging

The flags above enable or disable additional logging. Note though that the logging is verbose, and should be turned off when not activly needed, as it may interfere with normal serial operation.