Skip to main content

Scripting with CAN Bus Debugger

The CAN Bus Debugger device is capable of running custom user developed scripts. These scripts are created in Berry Script Language and can be loaded onto the device's SD card. The device exposes an API that can then be used to perform various CAN actions, access the file system on the SD card etc.

[WARNING]

Performing certain actions with this tool may completely halt a CAN bus. You should not perform any actions on a CAN Bus until the system is deemed safe to do so.

Creating Scripts

Scripts must be developed in Berry Script Language. If you're not familiar with Berry, a good resource to get started is: Berry Introduction (in 20 minutes or less). The current version of Berry Script Language used on the device is from the main branch, commit 23c6576. The table below details support for the default Berry lang modules.

Berry ModuleSupported
Strings✅
JSON✅
Math✅
Time❌
File System✅
OS✅
Global✅
Sys✅
Debug❌
Garbage Collector✅
Solidify❌
Introspect✅
Strict✅

CAN Debugger API​

In addition to Berry's default functionality, CAN Bus Debugger exposes an API to perform actions on the CAN.

The types used in the documentation below are documented further in Chapter 2 of the Berry documentation.

Classes​

Available classes:

  • CANFrame

CANFrame

Description

Contains all the information required to create and read CAN frames.

Getters
  • getID(): Gets the CAN ID of the frame.
    • Parameter: None.
    • Returns: (integer) The frame ID.
  • getIDE(): Gets the IDE flag state of the frame.
    • Parameter: None.
    • Returns: (boolean) true if the IDE flag is set, else false.
  • getRTR(): Gets the RTR flag state of the frame.
    • Parameter: None.
    • Returns: (boolean) true if the RTR flag is set, else false.
  • getData(): Gets the data field of the frame. Use the size() function to get the data length.
    • Parameter: None.
    • Returns: (bytes) The data as a byte array.
Setters
  • setID(): Sets the frame ID. Ensure you also set the appropriate value of the IDE flag.
    • Parameter: (integer) The ID of the frame.
    • Returns: nil.
  • setIDE(): Sets the IDE flag state of the frame.
    • Parameter: (boolean) true to set, false to clear.
    • Returns: nil.
  • setRTR(): Sets the RTR flag state of the frame.
    • Parameter: (boolean) true to set, false to clear.
    • Returns: nil.
  • setData(): Sets the data field of the frame.
    • Parameter: (byte array) The data to set.
    • Returns: nil on bad parameter, false on invalid byte array size, true on success.

CAN Functions​

Available CAN functions:

cbd_start_can(baud_rate, sample_point, enable_terminator, enable_one_shot, enable_listen_only)

Description

Starts the device's CAN with the desired baud rate and sample point. If the CAN was previously running, it must be stopped before calling this function.

This function does not guarantee the baud rate and sample point will be exactly as specified, but will attempt to use timing as close as possible given the CAN base clock of 80Mhz and the device constraints. If you need to be exact, please use the cbd_start_can_with_timing function and consider using the CAN Bit Timing Calculator.

Parameters
  • baud_rate (integer): The desired CAN baud rate.
  • sample_point (real): The desired CAN sample point.
  • enable_terminator (boolean): true if the device terminator should be enabled, else false
  • enable_one_shot (boolean): true if one shot mode should be enabled, else false
  • enable_listen_only (boolean): true if listen only mode should be enabled, else false
Returns
  • nil: On incorrect parameter.
  • false: On bit timing calculation failure or CAN already running.
  • true: On success.

cbd_start_can_with_timing(prescaler, tseg1, tseg2, sjw, enable_terminator, enable_one_shot, enable_listen_only)

Description

Starts the devices CAN with the provided bit timing. If the CAN was previously running, it must be stopped before calling this function.

Along with the constraints listed on the parameters below, the following restrictions apply:

  • tseg1 + tseg2 must be >= 3 and <= 384
  • tseg2 <= tseg1
  • sjw<= tseg2

CAN Bus Debugger uses a CAN base clock of 80Mhz. To help calculate parameters, consider using the CAN Bit Timing Calculator.

Parameters
  • prescaler (integer): The value of the bit timing prescaler. Must be >= 1 and <= 512.
  • tseg1 (integer): The value of the bit timing segment 1. Must be >= 1 and <= 256.
  • tseg2 (integer): The value of the bit timing segment 2. Must be >= 2 and <= 128.
  • sjw (integer): The value of the bit timing sync jump width. Must be >= 1 and <= 128.
  • enable_terminator (boolean): true if the device terminator should be enabled, else false
  • enable_one_shot (boolean): true if one shot mode should be enabled, else false
  • enable_listen_only (boolean): true if listen only mode should be enabled, else false
Returns
  • nil: On incorrect parameter.
  • false: On bit timing calculation failure or CAN already running.
  • true: On success.

cbd_stop_can()

Description

Stops the CAN on the device.

Parameters
  • None.
Returns
  • nil: Always.

cbd_tx_frame(frame)

Description

Queues a frame for transmission on the CAN bus. The device can queue up to 256 frames in the transmit FIFO.

Ensure the CAN is first started with cbd_start_can or cbd_start_can_with_timing. If the CAN is started in listen only mode, nothing will be queued.

Parameters
  • frame (CANFrame): The frame to send on the bus.
Returns
  • false: Frame queue full or invalid state.
  • true: Frame successfully queued.

cbd_rx_frame()

Description

Pops the next frame from the device's receive FIFO. The device can queue up to 256 frames in the FIFO. If the FIFO is full, frames will not be pushed onto the FIFO until more space is available. On higher speed buses, consider using the cbd_rx_filter family of functions.

Ensure the CAN is first started with cbd_start_can or cbd_start_can_with_timing.

Parameters
  • None.
Returns
  • nil: No frames available in the FIFO.
  • instance (CANFrame): The frame that was popped off the receive FIFO.

cbd_rx_clear()

Description

Empties the device's receive FIFO. The device can queue up to 256 frames in the FIFO. If the FIFO is full, frames will not be pushed onto the FIFO until more space is available.

Parameters
  • None.
Returns
  • nil: Always.

cbd_rx_filter_start_buffer_mode(frame_id)

Description

Starts the CAN receive filter in buffer mode. The buffer filter can hold a maximum of 32 frames and is independent to the standard receive FIFO. Once the buffer is full, frames will not be captured by the filter.

Items can be acquired from the filter buffer using the cbd_rx_filter_get_frame function. The number of frames currently captured in the buffer can be checked with the cbd_rx_filter_get_frame_count function and cleared with the cbd_rx_filter_clear function.

Only one of the buffer filter and slot filter can be enabled at a time. Calling this function or the cbd_rx_filter_start_slot_mode function again will disable this filter and reconfigure with the new settings.

This function can be called before starting the CAN.

Parameters
  • frame_id (integer): The ID of the frame to capture.
Returns
  • nil: On incorrect parameter.
  • false: On failure to create the filter.
  • true: On success.

cbd_rx_filter_start_slot_mode(frame_ids[])

Description

Starts the CAN receive filter in slot mode. The slot mode filter takes a list of up to 32 frame IDs and reports the last captured frame for each of those IDs. When a new frame is captured that matches one of the filter IDs, it replaces the old value. This filter runs independent to the standard receive FIFO.

Items can be acquired from the slot filter using the cbd_rx_filter_get_frame function. The index provided to the cbd_rx_filter_get_frame function maps to the index of the ID provided to this function. That is, if the frame ID at index 2 of this function was 0x21FA and you wanted to acquire the last received frame with this ID, you would call cbd_rx_filter_get_frame with index 2. The number of frames currently captured in the slots can be checked with the cbd_rx_filter_get_frame_count function. All slots can be cleared with the cbd_rx_filter_clear function.

Only one of the buffer filter and slot filter can be enabled at a time. Calling this function or the cbd_rx_filter_start_slot_mode function again will disable this filter and reconfigure with the new settings.

This function can be called before starting the CAN.

Parameters
  • frame_ids[] (list[int]): The list of frame IDs to capture. Maximum length of the list is 32.
Returns
  • nil: On incorrect parameter.
  • false: On failure to create the filter.
  • true: On success.

cbd_rx_filter_stop()

Description

Stops the current CAN receive filter. This does not clear the slots/buffer and as a result functions such as cbd_rx_filter_get_frame can still be used to get the values before the filter was stopped.

Parameters
  • None.
Returns
  • nil: Always.

cbd_rx_filter_get_frame(index)

Description

Gets a frame from the current CAN receive filter. Depending on the configured mode, this function operates differently.

In buffer mode, the index provided is the index of the frame to acquire from the buffer. Index 0 is the first frame captured by the filter and index 31 is the last frame captured. The cbd_rx_filter_get_frame_count function can be used to query the current buffer fill level.

In slot mode, the index provided to this function maps to the index of an ID provided to the cbd_rx_filter_start_slot_mode function. That is, if the frame ID at index 2 of cbd_rx_filter_start_slot_mode was 0x21FA and you wanted to acquire the last received frame with this ID, you would call this function with index set to a value of 2.

Parameters
  • index (integer): The index of the frame to get from the receive filter.
Returns
  • nil: Frame at the provided index is not available.
  • instance (CANFrame): The frame at the provided index.

cbd_rx_filter_get_frame_count()

Description

Gets a frame for the current configured CAN receive filter.

In buffer mode, the frame count indicates the number of frames in the buffer. In slot mode, the count indicates the number of filter slots that have matched a received frame at least once.

Parameters
  • None.
Returns
  • int: The number of frames available in the CAN receive filter.

cbd_rx_filter_clear()

Description

Clears all frames from the current configured CAN receive filter.

Parameters
  • None.
Returns
  • nil: Always.

Utility Functions​

sleep(time)

Description

Puts the script to sleep for the given number of milliseconds.

Note that the resolution of this function is 2ms and will only guarantee the script sleeps for at least that time. For instance, if you call this function with a sleep time of 501ms, the function will only guarantee the script sleeps for at least 502ms.

Parameters
  • time (integer): The number of milliseconds to sleep.
Returns
  • nil: Always.

print_to_screen(message)

Description

Prints a message to the console displayed on the screen of the CAN Bus Debugger device.

This variant of the print function will ensure the provided message appears on a new line.

Parameters
  • message (string): The message to print to the device console (511 chars max).
Returns
  • nil: Always.

print_to_screen_raw(message)

Description

Prints a message to the console displayed on the screen of the CAN Bus Debugger device.

This variant of the print function does not ensure the provided message appears on a new line.

Parameters
  • message (string): The message to print to the device console (511 chars max).
Returns
  • nil: Always.

user_prompt(message, left_btn_text, right_btn_text)

Description

Prompts the user for input by displaying a dialog on the CAN Bus Debugger device with the given text.

The script is paused until the user has selected an option.

Parameters
  • message (string): The message to display in the dialog on the device (255 chars max).
  • left_btn_text (string): The text to display on the left button of the dialog (9 chars max).
  • right_btn_text (string): The text to display on the right button of the dialog (9 chars max).
Returns
  • 0 (num): The user selected the left button option.
  • 1 (num): The user selected the right button option.
  • nil (num): Invalid args or internal error.

user_message(message, btn_text)

Description

Displays a dialog on the CAN Bus Debugger device with the given text.

The script is paused until the user has selected 'OK'.

Parameters
  • message (string): The message to display in the dialog on the device (255 chars max).
Returns
  • true (boolean): The dialog was displayed to the user.
  • nil (num): Invalid args or internal error.

Loading Scripts onto the Device​

Scripts can be loaded onto the device by placing them in the /scripts folder on the SD card. The SD card can be accessed by either removing it from the device and plugging directly into a PC, or by attaching the device to a PC via USB cable while the CAN is not in use and the device preferably in the main menu.

Running Scripts​

To execute a script on the device, first navigate to the Apps menu from the Main Menu. Once in the Apps menu, select the Scripts app. The device will then display the Script List screen as shown in the image below. This screen contains a list of all *.berry scripts in the /scripts folder on the device's SD card. The script list can be navigated using the up/down buttons and a script selected by pressing the ✔ button on the keypad.


After selecting a script, the Script Runner screen will be displayed. Scripts can be started by using the 'Start' button and aborted by using the 'Terminate' button once the script has started. If the script encounters any errors, they will be printed to the console.