API Reference - devilhyt/lump-device-builder-library GitHub Wiki
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.
Note
Some parts have been simplified for ease of understanding, so the source code may look a bit different.
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 (usuallyHardwareSerial
). -
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 ofLumpMode
). -
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.
- Valid range:
-
fwVersion
: Firmware version (default:10000000
).- Valid range:
[10000000..99999999]
. - The value
10000000
represents v1.0.00.0000.
- Valid range:
-
hwVersion
: Hardware version (default:10000000
).- Valid range:
[10000000..99999999]
. - The value
10000000
represents v1.0.00.0000.
- Valid range:
-
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.
-
Note
This function automatically clears the flag after checking.
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.
-
Note
This function automatically clears the flag after checking.
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 themode
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.
-
-
Parameters
-
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.
-
-
Parameters
-
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.
-
-
Parameters
-
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.
-
-
Parameters
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
""
ornullptr
. - Must start with a letter (
A–Z
,a–z
).
If invalid, the name will be set to the string
"null"
. - Must not be an empty string
-
Length limit (excluding null terminator):
- If
power
parameter isfalse
:11
(default) - If
power
parameter istrue
:5
Names exceeding the limit will be truncated.
- If
-
-
dataType
: Data type.- Possible values:
DATA8
,DATA16
,DATA32
,DATAF
.
- Possible values:
-
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]
-
- The maximum depends on data type due to 32-byte payload limit:
-
figures
: Number of characters shown in the view and datalog (including the decimal point).- Valid range:
[0..15]
- Valid range:
-
decimals
: Number of decimals shown in view and data log.- Valid range:
[0..15]
- Valid range:
-
symbol
: Symbol of the measurement unit (default:""
).- Rules:
- Set to empty string
""
ornullptr
if not required. - Length limit (excluding null terminator):
4
- Set to empty string
- Rules:
-
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]
.
- When set to
-
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]
.
- When set to
-
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]
.
- When set to
-
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
.
- Possible values:
-
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
.
- Possible values:
-
power
: Whether to enable constant power on SPIKE Hub pin 2 (default:false
). -
flagsInName
: Whether thename
parameter contains flags (default:false
).- If set to
true
, flags can be added to thename
parameter. In this case, thepower
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.
- If set to
-
Caution
When the power
parameter is set to true
in any mode, constant power on SPIKE Hub pin 2 is enabled across all modes.
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.
-
-
Parameters
-
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