Trickle configuration (ITk)

This section describes the API to interface felix-trickle to set the trickle memory and settings. It is only relevant for systems using a firmware that supports trickle configuration (ITk).

For all functions except append_trickle_config, the FID is the virtual FID of felix-trickle.

Setting the trickle memory

1. Create a new trickle configuration using the create_trickle_config function.

virtual void FelixClientThreadExtension520::create_trickle_config() = 0

This function creates a new blank trickle configuration.

2. Append the configuration for each frontend using the append_trickle_config function.

virtual void FelixClientThreadExtension520::append_trickle_config(const std::uint64_t fid, const std::vector<uint8_t> &payload) = 0

Adds data to the current trickle configuration.

Throws:

felix::TrickleLogicException – if called before create_trickle_config()

Parameters:

• elink – The fid of the FE device

• payload – The binary payload data

3. Send the configuration to the firmware using the send_trickle_config function.

virtual void FelixClientThreadExtension520::send_trickle_config(std::uint64_t fid) = 0

Send trickle configuration to a FELIX device.

Throws:

• felix::TrickleLogicException – if called before append_trickle_config()

• felix::SendWhileConnectionDownException – if the connection was lost and is being re-established

• felix::ResourceNotAvailableException – if no network buffers were available (try again)

• felix::MessageTooBigException – if message was too big (retrying will fail again)

• felix::BusException – if the tag is not found in the bus

Parameters:

• fid – The target FELIX device ID

• data – The binary payload for the trickle configuration

Controlling trickle configuration

The trickle configuration can be started and stopped using the start_trickle and stop_trickle functions.

virtual void FelixClientThreadExtension520::start_trickle(std::uint64_t fid) = 0

Start trickle sending on a FELIX device.

This function sends a command to start trickle sending on a FELIX device.

Throws:

• felix::SendWhileConnectionDownException – if the connection was lost and is being re-established

• felix::ResourceNotAvailableException – if no network buffers were available (try again)

• felix::MessageTooBigException – if message was too big (retrying will fail again)

• felix::BusException – if the tag is not found in the bus

Parameters:

fid – The target FELIX device ID

virtual void FelixClientThreadExtension520::stop_trickle(std::uint64_t fid) = 0

Stop trickle sending on a FELIX device.

This function sends a command to stop trickle sending on a FELIX device.

Throws:

• felix::SendWhileConnectionDownException – if the connection was lost and is being re-established

• felix::ResourceNotAvailableException – if no network buffers were available (try again)

• felix::MessageTooBigException – if message was too big (retrying will fail again)

• felix::BusException – if the tag is not found in the bus

Parameters:

fid – The target FELIX device ID

The BCIDs between which the trickle configuration is active can be selected using the select_trickle_bcids function and the speed can be throttled using the throttle_trickle function.

virtual void FelixClientThreadExtension520::select_trickle_bcids(std::uint64_t fid, std::uint32_t first_bcid, std::uint32_t last_bcid) = 0

Configure BCID range for trickle sending.

This function sends a command to configure the BCID range for trickle sending. DISCALIMER: it has not yet been implemented.

Throws:

• felix::SendWhileConnectionDownException – if the connection was lost and is being re-established

• felix::ResourceNotAvailableException – if no network buffers were available (try again)

• felix::MessageTooBigException – if message was too big (retrying will fail again)

• felix::BusException – if the tag is not found in the bus

Parameters:

• fid – The target FELIX device ID

• first_bcid – First BCID in the range

• last_bcid – Last BCID in the range

virtual void FelixClientThreadExtension520::throttle_trickle(std::uint64_t fid, std::uint32_t throttle_factor) = 0

Configure throttling factor for trickle sending.

This function sends a command to configure the throttling factor that slows firmware trickling. DISCLAIMER: it has not yet been implemented.

Throws:

• felix::SendWhileConnectionDownException – if the connection was lost and is being re-established

• felix::ResourceNotAvailableException – if no network buffers were available (try again)

• felix::MessageTooBigException – if message was too big (retrying will fail again)

• felix::BusException – if the tag is not found in the bus

Parameters:

• fid – The target FELIX device ID

• throttle_factor – slows trickling by N times [1 = no throttle]

Caution

The functionality for both functions is not implemented in the firmware yet.

Note

A throttle factor of 1 means no throttling, 2 means half speed, etc.

Important

• create_trickle_config() always resets the client-side state.

• send_trickle_config() always overwrites the server-side configuration.

• While trickle is running, only stop_trickle() is allowed.

Code Example

fct.create_trickle_config();

for (const auto& [frontend_fid, config] : trickle_config) {
  fct.append_trickle_config(frontend_fid, config);
}

fct.send_trickle_config(trickle_fid);

fct.select_trickle_bcids(trickle_fid, 0, 100);
fct.throttle_trickle(trickle_fid, 2);

fct.start_trickle(trickle_fid);
fct.stop_trickle(trickle_fid);