SDK Docs
Connection
Get Bluetooth Advertising Name
Returns null-terminated string with the BLE advertising name (e.g., "BL-ABCD").
Parameters: None
Returns:
Name - (string) BLE advertising name
Drive
Raw Motors
Run left and right motors at a speed between 0 and 255. Set driving mode using flags.
Parameters:
LeftMode - (Raw Motor Modes - uint8) Drive mode: 0x0-off, 0x1-forward, 0x2-reverse
LeftSpeed - (uint8) Proportional to 0-255 input
RightMode - (Raw Motor Modes - uint8) Drive mode: 0x0-off, 0x1-forward, 0x2-reverse
RightSpeed - (uint8) Proportional to 0-255 input
Returns: None
Reset Yaw
Sets current yaw angle to zero. (ie current direction is now considered 'forward'.)
Parameters: None
Returns: None
Drive With Heading
Drive towards a heading at a particular speed. Flags can be set to modify driving mode.
Parameters:
Speed - (uint8) 0 to 255 value
Heading - (uint16) 0 to 359 degrees (0 degrees is forward, 90 degrees is to the right, 180 degrees is back, and 270 is to the left)
Flags - (Drive Flags - uint8) Relevant flags: Drive Reverse, Boost, Fast Turn Mode
Returns: None
Enable Motor Stall Notify
Enables motor stall notifications.
Parameters:
IsEnabled - (bool) True for enable. False for disable
Returns: None
Motor Stall Notify
Motor stall protection change notification.
Parameters: None
Returns:
MotorIndex - (Motor Indexes - uint8) ID of motor that we want an alert for when the status has changed.
IsTriggered - (bool) True when protection triggered. False when protection resumed normal
Enable Motor Fault Notify
Enables notification for when there is a motor fault.
Parameters:
IsEnabled - (bool) True for enable. False for disable
Returns: None
Motor Fault Notify
Notification that a motor fault has occurred.
Parameters: None
Returns:
IsFault - (bool) True for fault. False for no fault
Get Motor Fault State
Get the motor fault state.
Parameters: None
Returns:
IsFault - (bool) True for fault. False for no fault
Enums:
Raw Motor Modes
Off: 0
Forward: 1
Reverse: 2
Motor Indexes
Left Motor Index: 0
Right Motor Index: 1
Bitmasks:
Drive Flags
Drive Reverse: bit 0
Boost: bit 1
Fast Turn: bit 2
Left Direction: bit 3
Right Direction: bit 4
Enable Drift: bit 5
IO
Set All Leds
LED affected mask can affect up to 32 LEDs simultaneously. 0 = not affected. 1 = affected (update this LED). If mask value is set to 1, you must provide a value in the LED data array.
Parameters:
LedGroup - (Led Groups - uint32) Bitmask selecting which LEDs to change (32-bit).
LedBrightnessValues - (uint8[32]) Array of RGB values for each of the selected LEDs (1 to 32 bytes; length depends on robot).
Returns: None
Get Active Color Palette
The response data will list all assigned color palette slots in the system.
Parameters: None
Returns:
RgbIndexBytes - (uint8[48]) struct array -- index, red, green, blue -- that stores the contents of the active color palette.
Set Active Color Palette
Each entry in the array corresponds to one color slot in the system. Any unmentioned slot indices will be marked unassigned.
Parameters:
RgbIndexBytes - (uint8[48]) struct array -- index, red, green, blue -- that stores the contents of the color palette to be set as the active color palette.
Returns: None
Get Color Identification Report
The response to this command will provide an array of color palette entries that would match on the provided color with higher confidence than the given threshold.
Parameters:
Red - (uint8) Red ('R') value of the color to be matched.
Green - (uint8) Green ('G') value of the color to be matched.
Blue - (uint8) Blue ('B') value of the color to be matched.
ConfidenceThreshold - (uint8) How closely the palette should match the provided color. The confidence threshold is in [0, 255].
Returns:
IndexConfidenceByte - (uint8[24]) struct array -- index, confidence -- that contains the index of the palette that best matches the provided color and a confidence level for how closely the palette matches the provided color.
Load Color Palette
Loads the specified color palette into the active palette.
Parameters:
PaletteIndex - (Specdrums Color Palette Indicies - uint8) The index of (number that identifies) the color palette to be loaded.
Returns: None
Save Color Palette
Stores the active palette into the palette at palette index (see table above).
Parameters:
PaletteIndex - (Specdrums Color Palette Indicies - uint8) The index of (number that identifies) the color palette to be stored.
Returns: None
Release Led Requests
Releases LED requests to show the idle indication.
Parameters: None
Returns: None
Enums:
Specdrums Color Palette Indicies
Default: 0
Midi: 1
Specdrums Color Palette Indicies
Default: 0
Midi: 1
Bitmasks:
Led Groups
Power
Sleep
Put robot into a soft sleep state. Driving, LEDS, and sensors are disabled.
Parameters: None
Returns: None
Wake
Wake up the system from soft sleep. Nothing to do if awake.
Parameters: None
Returns: None
Get Battery Percentage
Get usable battery percentage remaining.
Parameters: None
Returns:
Percentage - (uint8) Percent of battery that is remaining.
Get Battery Voltage State
Returns the current battery state
Parameters: None
Returns:
State - (Battery Voltage States - uint8) The current battery state.
Will Sleep Notify
Notification triggered 10 seconds before soft/deep sleep.
Parameters: None
Returns: None
Did Sleep Notify
Notification triggered when robot has entered soft/deep sleep.
Parameters: None
Returns: None
Enable Battery Voltage State Change Notify
Enables or disables notifications for changes to battery voltage state.
Parameters:
IsEnabled - (bool) Indicates whether battery voltage state notifications should be enabled. True is enabled. False is disabled.
Returns: None
Battery Voltage State Change Notify
Notification for battery voltage state change.
Parameters: None
Returns:
State - (Battery Voltage States - uint8) An enum representing the battery voltage state: 0 = unknown, 1 = ok, 2 = low, 3 = critical.
Get Battery Voltage In Volts
Returns the most recent battery voltage reading in volts. This results in a 'Command Failed' API error if the platform does not support calibration. Note that this command does not get a new voltage reading; it returns the most recently read value, which is updated once per second on most robots. To force the battery system to read a new value, use the 'Force Battery Refresh' command.
Parameters:
ReadingType - (Battery Voltage Reading Types - uint8) Integer value indicating the type of reading you are seeking.
Returns:
Voltage - (float, volts) Most recently read voltage of the battery.
Get Battery Voltage State Thresholds
Returns the battery voltage state thresholds and hysteresis value. The hysteresis value is added to the thresholds for rising voltages -- e.g., the voltage must be less than the low threshold to change the state to 'low battery' but it must be greater than (low threshold + hysteresis) to go back to the 'ok battery' state.
Parameters: None
Returns:
CriticalThreshold - (float) Float value indicating the voltage under which the battery should be read as 'critical'.
LowThreshold - (float) Float value indicating the voltage under which the battery should be read as 'low'.
Hysteresis - (float) Float value containing the amount by which the voltage must be above the critical or low thresholds in order for the battery to not be considered 'critical' or 'low'.
Get Current Sense Amplifier Current
Get the current draw, in AMPS, from a current sense amplifier
Parameters:
AmplifierId - (Amplifier Ids - uint8) Motor amplifier id
Returns:
AmplifierCurrent - (float) The value of the current coming from the amplifier specified in the input.
Enums:
Battery Voltage Reading Types
Calibrated And Filtered: 0
Calibrated And Unfiltered: 1
Uncalibrated And Unfiltered: 2
Amplifier Ids
Left Motor: 0
Right Motor: 1
Sensor
Enable Gyro Max Notify
Enables the Async messages for when the Gyro max is hit.
Parameters:
IsEnabled - (bool) Boolean set for if you would like a notification when the Gyro max is hit. True for enabled. False for disabled.
Returns: None
Gyro Max Notify
Occurs when the robot spins faster than the sensor can see in any axis.
Parameters: None
Returns:
Flags - (Gyro Max Flags - uint8) The values signify things are as such: 0 = Max + X, 1 = Max - X, 2 = Max + Y, 3 = Max - Y, 4 = Max + z, 5 = Max - Z
Reset Locator X And Y
Resets the locator module's current X and Y values to 0.
Parameters: None
Returns: None
Set Locator Flags
Sets flags for the locator module.
Parameters:
Flags - (Locator Flags - uint8) Auto calibrate: When set, the robot will maintain the same X - Y axis from initial startup. When cleared, the robot will reset the X - Y axis orientation when a driving yaw reset command is sent.
Returns: None
Get Bot To Bot Infrared Readings
An 8-bit value is returned for each infrared sensor, assigned by mask. Mask description on BOLT: 32'h0000_00ff: front left sensor 32'h0000_ff00: front right sensor 32'h00ff_0000: back right sensor 32'hff00_0000: back left sensor
Parameters: None
Returns:
SensorData - (Infrared Sensor Locations - uint32) If the register reads a value between 0 - 15, then a message of that ID has been received. If the data returned is 255, the register is empty. For RVR+/RVR, the message is only kept for 1second before it's reset back to 255.
Get RGBC Sensor Values
Return raw data being read by RGBC sensor on each sensor channel
Parameters: None
Returns:
RedChannelValue - (uint16) None
GreenChannelValue - (uint16) None
BlueChannelValue - (uint16) None
ClearChannelValue - (uint16) None
Start Robot To Robot Infrared Broadcasting
For robot following, broadcasting robots emit two codes: one for long distance (3 meters +), and one for short distance (< 1 meter). Following robots use both of these codes to determine direction and distance from the broadcasting robot.
Parameters:
FarCode - (uint8) Code between 0 and 7 that the robot emits for long distance (3+ meters) communication so that bots receiving it will know that it is further away.
NearCode - (uint8) Code between 0 and 7 that the robot emits for short distance (<1 meters) communication so that bots receiving it will know that it is closer.
Returns: None
Start Robot To Robot Infrared Following
Registers a far code and near code for a following robot to follow. Following robots use the far code and near code emitted by a broadcaster bot to determine direction and distance to travel.
Parameters:
FarCode - (uint8) Code between 0 and 7 that the robot emits for long distance (3+ meters) communication so that bots receiving it will know that it is further away.
NearCode - (uint8) Code between 0 and 7 that the robot emits for short distance (<1 meters) communication so that bots receiving it will know that it is closer.
Returns: None
Stop Robot To Robot Infrared Broadcasting
Halts current broadcasting or following. De-registers far code and near code on broadcasting or following robot.
Parameters: None
Returns: None
Robot To Robot Infrared Message Received Notify
Async sent when a registered robot to robot infrared message is received. In response returns the infrared code listened for.
Parameters: None
Returns:
InfraredCode - (uint8) Infrared code received from within the list of the channels listened for.
Get Ambient Light Sensor Value
Ambient light value is returned; higher = more light!
Parameters: None
Returns:
AmbientLightValue - (float) higher = more light
Stop Robot To Robot Infrared Following
Halts current following. De-registers far code and near code on following robot.
Parameters: None
Returns: None
Start Robot To Robot Infrared Evading
Registers a far code and near code for a evading robot to evade. Evading robots use the far code and near code emitted by a broadcaster bot to determine direction and distance to travel.
Parameters:
FarCode - (uint8) Code between 0 and 7 that the robot emits for long distance (3+ meters) communication so that bots receiving it will know that it is further away.
NearCode - (uint8) Code between 0 and 7 that the robot emits for short distance (<1 meters) communication so that bots receiving it will know that it is closer.
Returns: None
Stop Robot To Robot Infrared Evading
Halts current evading. De-registers far code and near code on evading robot.
Parameters: None
Returns: None
Enable Color Detection Notify
Enable or disable asynchronous color detection notifications. The user must provide an interval and a confidence threshold
Parameters:
IsEnabled - (bool) True for enable. False for disable
Interval - (uint16, milliseconds) Interval, in milliseconds, that color detection asyncs will be sent.
MinimumConfidenceThreshold - (uint8) The minimum confidence level, from 0 to 255, that must be met before an async is sent.
Returns: None
Color Detection Notify
Notification sent on the interval set by the user in enable_color_detection_notification with information about the color detected. The color classification ID 0xFF is a special value indicating that the color could not be identified (e.g., because the reading was too dark). This is expected behavior when the ring is tapped in the air with the sensor facing out.
Parameters: None
Returns:
Red - (uint8) Red value detected.
Green - (uint8) Green value detected.
Blue - (uint8) Blue value detected.
Confidence - (uint8) Level of confidence in color classification ID, from 0 (0% confidence) to 255 (100% confident)
ColorClassificationId - (uint8) Toy-dependent ID for color classification.
Get Current Detected Color Reading
Note: this does not return anything. Instead, a color_detection_notify async will be sent after measurement with the answer.
Parameters: None
Returns: None
Enable Color Detection
Enables the color detection module.
Parameters:
IsEnabled - (bool) True for enable. False for disable
Returns: None
Configure Streaming Service
Configure streaming services.
Parameters:
Token - (uint8) None
Configuration - (Streaming Data Sizes - uint8[15]) Array containing the configuration of the client, like the service ID and size.
Returns: None
Start Streaming Service
Start all streaming services for a client
Parameters:
Period - (uint16) Interval between sensor streaming packets in milliseconds.
Returns: None
Stop Streaming Service
Stops all streaming services for a client
Parameters: None
Returns: None
Clear Streaming Service
Clears all streaming services for a client
Parameters: None
Returns: None
Streaming Service Data Notify
Streaming data notification for a client configuration
Parameters: None
Returns:
Token - (uint8) None
SensorData - (uint8[9999]) Array containing the configuration of the client, like the data.
Enable Robot Infrared Message Notify
Starts listening for infrared messages sent to the robot and will send an async message when received.
Parameters:
IsEnabled - (bool) True for enable. False for disable
Returns: None
Send Infrared Message
Send specified code to any robot in the vicinity. The on/off for each sensor is controlled individually but there can only be one range for all sensors. Therefore, the acceptable combination of emitters strength would be: 5, 5, 0, 0 or 5, 5, 5, 5 or 0, 0, 0, 5, etc.
Parameters:
InfraredCode - (uint8) The only valid messages to send this way have an ID between 0 and 7.
FrontStrength - (uint8) The range goes from 0-64, where 0 is no message sent, and 64 is the longest achievable range.
LeftStrength - (uint8) The range goes from 0-64, where 0 is no message sent, and 64 is the longest achievable range.
RightStrength - (uint8) The range goes from 0-64, where 0 is no message sent, and 64 is the longest achievable range.
RearStrength - (uint8) The range goes from 0-64, where 0 is no message sent, and 64 is the longest achievable range.
Returns: None
Get Motor Temperature
Get the motor temperature (calculated from motor current) for given a motor index.
Parameters:
MotorIndex - (Motor Indexes - uint8) Indicates which motor we would like the metrics.
Returns:
WindingCoilTemperature - (float) Temperature of the winding coil. Reported in Celsius.
CaseTemperature - (float) Temperature of the case. Reported in Celsius.
Get Motor Thermal Protection Status
Get motor thermal protection status.
Parameters: None
Returns:
LeftMotorTemperature - (float, celsius) Temperature of the left motor in degrees Celsius
LeftMotorStatus - (Thermal Protection Status - uint8) Thermal protection status.
RightMotorTemperature - (float, celsius) Temperature of the right motor in degrees Celsius
RightMotorStatus - (Thermal Protection Status - uint8) Thermal protection status.
Enable Motor Thermal Protection Status Notify
Enable motor thermal protection status notifications.
Parameters:
IsEnabled - (bool) True for enable. False for disable
Returns: None
Motor Thermal Protection Status Notify
Motor thermal protection status notification.
Parameters: None
Returns:
LeftMotorTemperature - (float, celsius) Temperature of the left motor in degrees Celsius
LeftMotorStatus - (Thermal Protection Status - uint8) Thermal protection status.
RightMotorTemperature - (float, celsius) Temperature of the right motor in degrees Celsius
RightMotorStatus - (Thermal Protection Status - uint8) Thermal protection status.
Enums:
Streaming Data Sizes
Eight Bit: 0x00
Sixteen Bit: 0x01
Thirty Two Bit: 0x02
Motor Indexes
Left Motor Index: 0
Right Motor Index: 1
Bitmasks:
Gyro Max Flags
Max Plus X: bit 0
Max Minus X: bit 1
Max Plus Y: bit 2
Max Minus Y: bit 3
Max Plus Z: bit 4
Max Minus Z: bit 5
Locator Flags
Auto Calibrate: bit 0
Infrared Sensor Locations
Front Left: 0x000000FF
Front Right: 0x0000FF00
Back Right: 0x00FF0000
Back Left: 0xFF000000
System Info
Get Main Application Version
Gets the version of the main application.
Parameters: None
Returns:
Major - (uint16) The x value for version x.y.z
Minor - (uint16) The y value for version x.y.z
Revision - (uint16) The z value for version x.y.z
Get Bootloader Version
Gets the version of the bootloader.
Parameters: None
Returns:
Major - (uint16) The x value for version x.y.z
Minor - (uint16) The y value for version x.y.z
Revision - (uint16) The z value for version x.y.z
Get Board Revision
Gets the board revision number.
Parameters: None
Returns:
Revision - (uint8) The hardware version for the board.
Get Mac Address
Gets the robot's MAC address.
Parameters: None
Returns:
MacAddress - (string) A 12-byte string representing the robot's MAC address.
Get Stats Id
Gets the id number assigned by the company for activation tracking.
Parameters: None
Returns:
StatsId - (uint16) The ID number assigned by the company (for activation tracking).
Get Processor Name
Returns the processor name string (as specified to the System Info module). If no name is specified, returns an empty string or no string.
Parameters: None
Returns:
Name - (string) The processor name (string up to 16 characters, including optional null terminator).
Get SKU
Returns the SKU of the bot.
Parameters: None
Returns:
Sku - (string) SKU (null-terminated string).
Get Core Up Time In Milliseconds
Returns the time (in milliseconds) that has passed since the latest power cycle started.
Parameters: None
Returns:
UpTime - (uint64, milliseconds) Time (in milliseconds) since last application start up.
