This is the API reference for the LUMP Device Builder Library. It documents only the public interfaces. For comprehensive details about the library, please refer to the source code.

LUMP device class.

Create a device.

template <typename T>
LumpDevice<T>::LumpDevice(
    T *uart,
    uint8_t rxPin,
    uint8_t txPin,
    uint8_t type,
    uint32_t speed,
    LumpMode *modes,
    uint8_t numModes,
    uint8_t view        = LUMP_VIEW_ALL,
    uint32_t fwVersion  = 10000000,
    uint32_t hwVersion  = 10000000
);

• Parameters

  • T: Type of the serial interface (usually HardwareSerial).

  • uart: Serial interface used for UART communication (e.g., Serial0, Serial1).

  • rxPin: RX pin number of the serial interface.

  • txPin: TX pin number of the serial interface.

  • type: Device type.

  • speed: Communication speed.

  • modes: Device modes (must be an array of LumpMode).

  • numModes: Number of modes.

    • For SPIKE Hub: [1..16]

    • For EV3: [1..8]

      Modes beyond the limit will be ignored.

  • view: Number of modes to show in view and data log (default: LUMP_VIEW_ALL).

    • Valid range: [1..16].
    • Set to LUMP_VIEW_ALL to show all modes.

  • fwVersion: Firmware version (default: 10000000).

    • Valid range: [10000000..99999999].
    • The value 10000000 represents v1.0.00.0000.

  • hwVersion: Hardware version (default: 10000000).

    • Valid range: [10000000..99999999].
    • The value 10000000 represents v1.0.00.0000.

Starts the device.

void begin();

Finishes the device.

void end();

Runs the device.

void run();

Gets the device state.

LumpDeviceState state();

• Return: Device state.

Gets the device mode.

uint8_t mode();

• Return: Device mode.

Checks if the device is in communication phase.

bool isCommunicating();

• Return
  • true: The device is in communication phase.
  • false: Otherwise.

Checks for a newly received NACK.

bool hasNack();

• Return
  • true: A newly received NACK is available.
  • false: Otherwise.

Clears the command write data.

void clearCmdWriteData();

Checks for a newly received command write data.

bool hasCmdWriteData();

• Return
  • true: A newly received command write data is available.
  • false: Otherwise.

Reads the command write data.

template <typename U>
U *readCmdWriteData();

• Parameters
  • U: Type of the command write data.
• Return
  • U*: Pointer to the command write data array.

Clears the data message for the specified mode.

void clearDataMsg(uint8_t mode);

• Parameters
  • mode: Mode number.

Checks for a newly received data message for the specified mode.

bool hasDataMsg(uint8_t mode);

• Parameters
  • mode: Mode number.
• Return
  • true: A newly received data message is available.
  • false: Otherwise.

Reads the data message of the specified mode.

template <typename U>
U *readDataMsg(uint8_t mode);

• Parameters
  • U: Type of the data.
  • mode: Mode number.
• Return
  • U*: Pointer to the the data message array if the mode is valid and the data message is available.
  • nullptr: Otherwise.

• Sends a data value of the specified type.

  template <typename U>
  void send(U data);

  • Parameters
    • U: Type of the data.
    • data: A data value.

• Sends a data value of the specified type for a specific mode.

  template <typename U>
  void send(U data, uint8_t mode);

  • Parameters
    • U: Type of the data.
    • data: A data value.
    • mode: Mode number.

• Sends a data array of the specified type.

  template <typename U>
  void send(U *data, uint8_t num);
  
  template <typename U, size_t N>
  void send(U (*data)[N], uint8_t num);

  • Parameters
    • U: Type of the data.
    • N: Size of the data array.
    • data: Pointer to the data array.
    • num: Number of data in the data array.

• Sends a data array of the specified type for a specific mode.

  template <typename U>
  void send(U *data, uint8_t num, uint8_t mode);
  
  template <typename U, size_t N>
  void send(U (*data)[N], uint8_t num, uint8_t mode);

  • Parameters
    • U: Type of the data.
    • N: Size of the data array.
    • data: Pointer to the data array.
    • num: Number of data in the data array.
    • mode: Mode number.

Sets the watchdog timer callback functions.

void setWdtCallback(void (*initWdtCallback)(), void (*feedWdtCallback)(), void (*deinitWdtCallback)());

• Parameters
  • initWdtCallback: Callback function to initialize the watchdog timer.
  • feedWdtCallback: Callback function to feed the watchdog timer.
  • deinitWdtCallback: Callback function to deinitialize the watchdog timer.

Represents a mode of a LUMP device.

Creates a mode.

LumpMode::LumpMode(
  const char *name,
  uint8_t dataType,
  uint8_t numData,
  uint8_t figures,
  uint8_t decimals,
  const char *symbol = "",
  LumpValueSpan raw  = false,
  LumpValueSpan pct  = false,
  LumpValueSpan si   = false,
  uint8_t mapIn      = LUMP_INFO_MAPPING_NONE,
  uint8_t mapOut     = LUMP_INFO_MAPPING_NONE,
  bool power         = false,
  bool flagsInName   = false
);

• Parameters

  • name: Mode name.

    • Naming rules:

      • Must not be an empty string "" or nullptr.
      • Must start with a letter (A–Z, a–z).

      If invalid, the name will be set to the string "null".

    • Length limit (excluding null terminator):

      • If power parameter is false: 11 (default)
      • If power parameter is true: 5

      Names exceeding the limit will be truncated.

  • dataType: Data type.

    • Possible values: DATA8, DATA16, DATA32, DATAF.

  • numData: Number of data.

    • The maximum depends on data type due to 32-byte payload limit:
      • DATA8 (1 byte) : [1..32]
      • DATA16 (2 bytes): [1..16]
      • DATA32 (4 bytes): [1..8]
      • DATAF (4 bytes): [1..8]

  • figures: Number of characters shown in the view and datalog (including the decimal point).

    • Valid range: [0..15]

  • decimals: Number of decimals shown in view and data log.

    • Valid range: [0..15]

  • symbol: Symbol of the measurement unit (default: "").

    • Rules:
      • Set to empty string "" or nullptr if not required.
      • Length limit (excluding null terminator): 4

  • raw: Raw value span (default: false).

    • When set to false, this value span will not be provided to the host. The host will use the default range [0, 1023].

  • pct: Percentage value span (default: false).

    • When set to false, this value span will not be provided to the host. The host will use the default range [0, 100].

  • si: Scaled value span (default: false).

    • When set to false, this value span will not be provided to the host. The host will use the default range [0, 1023].

  • mapIn: Mode mapping for input side (default: LUMP_INFO_MAPPING_NONE).

    • Possible values: LUMP_INFO_MAPPING_NONE, LUMP_INFO_MAPPING_DIS, LUMP_INFO_MAPPING_REL, LUMP_INFO_MAPPING_ABS.
    • Optionally bitwise OR-ed with: LUMP_INFO_MAPPING_SUPPORT_FUNCTIONAL_MAPPING_2, LUMP_INFO_MAPPING_SUPPORT_NULL.

  • mapOut: Mode mapping for output side (default: LUMP_INFO_MAPPING_NONE).

    • Possible values: LUMP_INFO_MAPPING_NONE, LUMP_INFO_MAPPING_DIS, LUMP_INFO_MAPPING_REL, LUMP_INFO_MAPPING_ABS.
    • Optionally bitwise OR-ed with: LUMP_INFO_MAPPING_SUPPORT_FUNCTIONAL_MAPPING_2, LUMP_INFO_MAPPING_SUPPORT_NULL.

  • power: Whether to enable constant power on SPIKE Hub pin 2 (default: false).

  • flagsInName: Whether the name parameter contains flags (default: false).

    • If set to true, flags can be added to the name parameter. In this case, the power parameter will be ignored.
    • The total length of name and flags must be exactly 13 (5 for name + 1 null terminator + 6 flags + 1 null terminator).
    • See: https://github.com/pybricks/technical-info/blob/88a708c/uart-protocol.md#info_name.

Represents a value span for a mode.

• Creates a value span.

  LumpValueSpan(float min, float max);

  • Parameters
    • min: Minimum value of the span.
    • max: Maximum value of the span.

• Creates an empty value span.

  LumpValueSpan(bool isExist = false);

  • Parameters

    • isExist: Whether the value span exists (default: false).

  • Note: Used to allow the handshake process to skip sending value span information.

Represents the state of a LUMP device.

enum class LumpDeviceState : uint8_t;

Values

• Initialization phase
  • InitWdt: Initializing the watchdog timer.
  • Reset: Reseting the device.
• Handshake phase
  • InitAutoId: Initializing the AutoID.
  • WaitingAutoId: Waiting for the AutoID.
  • InitUart: Initializing the UART.
  • WaitingUartInit: Waiting for the UART initialization.
  • SendingType: Sending the device type.
  • SendingModes: Sending the numbers of modes and views.
  • SendingSpeed: Sending the communication speed.
  • SendingVersion: Sending the firmware and hardware version.
  • SendingName: Sending the mode name and flags.
  • SendingValueSpans: Sending the value spans.
  • SendingSymbol: Sending the symbol.
  • SendingMapping: Sending the mode mapping.
  • SendingFormat: Sending the data format.
  • InterModePause: Inter-mode pause.
  • SendingAck: Sending an ACK.
  • WaitingAckReply: Waiting for the ACK reply.
  • SwitchingUartSpeed: Switching UART to the communication speed.
• Communication phase
  • InitMode: Initializing the mode.
  • Communicating: Communicating with the host.
  • SendingNack: Sending a NACK.

Mode mapping flags.

typedef enum {...} lump_info_mapping_t;

Values

• LUMP_INFO_MAPPING_NONE: No flags are set.
• LUMP_INFO_MAPPING_NA0: N/A 0.
• LUMP_INFO_MAPPING_NA1: N/A 1.
• LUMP_INFO_MAPPING_DIS: DIS (Discrete [0, 1, 2, 3]).
• LUMP_INFO_MAPPING_REL: REL (Relative [-1..1]).
• LUMP_INFO_MAPPING_ABS: ABS (Absolute [min..max]).
• LUMP_INFO_MAPPING_NA5: N/A 5.
• LUMP_INFO_MAPPING_SUPPORT_FUNCTIONAL_MAPPING_2: Supports Functional Mapping 2.0+.
• LUMP_INFO_MAPPING_SUPPORT_NULL: Supports NULL value.

Short alias for LUMP data types.

typedef enum {...} lump_data_type_short_t;

Values

• DATA8: 8-bit signed integer.
• DATA16: little-endian 16-bit signed integer.
• DATA32: little-endian 32-bit signed integer.
• DATAF: little-endian 32-bit floating point.

LUMP NACK timeout thresholds (milliseconds).

#define LUMP_NACK_TIMEOUT 1500

Shows all modes in view and data log.

#define LUMP_VIEW_ALL 255

Disables automatic host type detection.

#define LUMP_HOST_DETECT_OFF