CANHardware UCMVirtual UCM
The can library implements CAN bus communication.
The can library is available and suitable for:
- ENP-CAN, using hardware port,
- ENP-RS-CAN-USB M2, using hardware port,
- Virtual UCM on Welotec Arrakis Mk3/Mk4 with CAN module installed, using 2 hardware ports,
- Virtual UCM on any PC using Generic IO interface.
can.new
CAN hardware ports must be configured before use.
-- @param connection_uri string Connection URI
-- @return object|nil, string|nil
function can.new(connection_uri)
end
Creates a new CAN client. The connection URI should specify the desired CAN device.
Use port schema to access hardware ports. On Virtual UCM you may also use gio schema for Generic IO.
On failure, it returns nil and an error message string.
Constants
client Object
client:send
-- @param id number CAN message ID
-- @param data string Data to send
-- @return string|nil
function client:send(id, data)
end
Sends a CAN message with the specified ID and data.
On success, the function returns nil. On failure, it returns an error message string.
Example
-- Send "Hello World" message with ID 0x213
local err = client:send(0x213, "Hello World")
if err ~= nil then
enapter.log("Error sending CAN message: " .. err, "error")
end
client:monitor
-- @param ids table List of CAN message IDs to monitor
-- @return table|nil, string|nil
function client:monitor(ids)
end
Starts monitoring specified CAN message IDs. This is useful when the business logic only requires the most recent value and does not rely on historical data.
On success, the function returns a new monitor object and nil. On failure, it returns nil and an error message string.
Example
-- Monitor messages with IDs 0x400, 0x213, 0x317, and 0x239
monitor, err = client:monitor({ 0x400, 0x213, 0x317, 0x239 })
if err ~= nil then
enapter.log("Error creating CAN monitor: " .. err, "error")
end
client:queue
-- @param ids table List of CAN message IDs to queue
-- @param size number Maximum number of messages to store per ID
-- @param policy can.DROP_OLDEST|can.DROP_NEWEST Drop policy
-- @return object|nil, string|nil
function client:queue(ids, size, policy)
end
Creates queues for incoming CAN messages with specified IDs. This is useful when the business logic requires historical data not just the the most recent value. Queue has maximum size per message ID.
When the policy is can.DROP_OLDEST, the oldest value in the queue is removed when the queue is full and new data arrives. When the policy is can.DROP_NEWEST, incoming data is discarded until older data is read from the queue.
On success, the function returns a new queue object and nil. On failure, it returns nil and an error message string.
Example
-- Create a queue for IDs 0x213 and 0x317, store up to 10 messages per ID,
-- drop oldest if no space left
local queue, err = client:queue({ 0x213, 0x317 }, 10, can.DROP_OLDEST)
if err ~= nil then
enapter.log("Error creating CAN queue: " .. err, "error")
end
monitor Object
monitor:pop
-- @param ids table List of CAN message IDs to monitor
-- @return table|nil, string|nil
function monitor:pop(ids)
end
Returns the stored value for the specified IDs.
Each i-th element in the result corresponds to the i-th message ID in the IDs list. Calling this method clears the monitor, so subsequent calls will return empty result for a given ID until new CAN data is received. If no data is available for a given ID, the corresponding element in the result will be nil.
On success, the function returns a table and nil. On failure, it returns nil and an error message string.
Example
-- Retrieve latest values for specific IDs
local data, err = monitor:pop({ 0x213, 0x317, 0x239 })
if err ~= nil then
enapter.log("Error retrieving CAN data: " .. err, "error")
else
-- data[1] corresponds to 0x213, data[2] → 0x317, data[3] → 0x239
enapter.log("Data received: " .. tostring(data[1]) .. ", " .. tostring(data[2]) .. ", " .. tostring(data[3]))
end
queue Object
queue:pop
-- @param id table CAN message ID
-- @return table|nil, string|nil
function queue:pop(id)
end
Returns the stored values for the specified ID. Calling this method clears the queue, so subsequent calls will return empty result until new CAN data is received. If no data is available, the result will always be empty.
On success, the function returns a table and nil. On failure, it returns nil and an error message string.
Example
-- Retrieve latest values for ID 0x317
local power_values, err = queue:pop(0x317)
if err ~= nil then
enapter.log("Error retrieving CAN queue data: " .. err, "error")
else
enapter.log("Power values: " .. table.concat(power_values, ", "))
end
queue:drops_count
-- @param id number CAN message ID
-- @return number|nil, string|nil
function queue:drops_count(id)
end
Returns the number of dropped packets.
On success, the function returns a number and nil. On failure, it returns nil and an error message string.
Example
-- Get the number of dropped messages for ID 0x213
local drops = queue:drops_count(0x213)
enapter.log("Drops of 0x213: " .. tostring(drops))