API Reference Documentation

Automatically generated API reference documentation.

PMACFilterController

class PMACFilterController

Class to subscribe for data messages and adjust attenuation of filter set.

Public Functions

PMACFilterController(const std::string &control_port, const std::string &publish_port, const std::vector<std::string> &subscribe_endpoints)

Constructor.

Setup ZeroMQ sockets

Parameters:

• control_port – [in] Port number to bind control socket to

• publish_port – [in] Port number to bind event stream publish socket to

• subscribe_endpoints – [in] Vector of endpoints (IP:PORT) to subscribe on for data messages

~PMACFilterController()

Destructor.

Close ZeroMQ sockets

void run()

Spawn data monitor thread and listen for control requests until shutdown.

Private Functions

bool _handle_request(const json &request, json &response)

Handle the JSON request from the control channel.

This method assumes request has contains a COMMAND field and accesses it without checking.

Throws:

Assertion – failed if there is no COMMAND field

Parameters:

• request – [in] json object of request

• response – [out] json object to add response to

Returns:

true if the request was applied successfully, else false

void _handle_status(json &response)

Handle a status request from the control channel.

Parameters:

response – [out] json object to add status to

bool _handle_config(const json &config)

Handle a configuration request.

Parameters:

config – [in] json object of config parameters

Throws:

json::type_error – if given a config parameter with the wrong type

Returns:

true if all given parameters applied successfully, false if one or more failed or no parameters found

bool _set_mode(const ControlMode mode)

Set the mode enum with value checking.

Parameters:

mode – [in] ControlMode (enum value) of mode to set

Returns:

true if the mode was set successfully, else false

bool _set_timeout(const float timeout)

Update timeout config variable from given value.

Parameters:

timeout – [in] Timeout value in seconds

Returns:

true if the mode was set successfully, else false

bool _set_positions(std::vector<int> &positions, const json new_positions)

Update the given positions vector from given new values.

Parameters:

• positions – [in] active filter positions vector - either this->in_positions_ or this->out_positions_

• new_positions – [in] json dictionary of new filter positions - e.g. {“filter1”: 100, “filter2”: -100, …}

Throws:

json::type_error – if given a config parameter with the wrong type

Returns:

true if at least one position was set, else false

bool _set_shutter_closed_position(const int shutter_closed_position)

Update the given shutter closed position from the given value.

Parameters:

shutter_closed_position – [in] shutter closed position

Returns:

true if the position was set, else false

bool _set_pixel_count_thresholds(json thresholds)

Set the in pixel count thresholds of the given histogram bins.

Parameters:

thresholds – [in] json dictionary of pixel count thresholds - e.g. {“high1”: 100, “low2”: 500, …}

Throws:

json::type_error – if given a config parameter with the wrong type

Returns:

true if at least one threshold was set, else false

void _process_data_channel()

Listen on ZeroMQ data channel for messages and hand off for processing.

This method should be run in a spawned thread and will return when shutdown_ is set to true

void _process_state_changes()

Update state based on mode changes from control thread and internal logic.

void _handle_data_message(zmq::message_t &data_message)

Process message and publish the resulting attenuation change.

Parameters:

data_message – [in] Message containing histogram data

void _transition_state(ControlState state)

Transition to the given state applying relevant logic for specific transitions.

void _process_singleshot_state()

Handle logic for singleshot mode.

This method assumes the controller is in singleshot mode

bool _process_data(const json &data)

Process message data.

Determine if the data json should be processed based on the frame number, check which threshold is triggered if any and adjust the attenuation level as necessary.

If PARAM_HIGH3 is triggered it will be processed regardless of the frame number.

Parameters:

data – [in] json structure of data message

Returns:

true if an attenuation change was made, else false

void _close_shutter()

Close shutter.

void _trigger_threshold(const std::string threshold)

Process filter adjustment.

Parameters:

threshold – [in] Name of threshold to trigger

void _set_attenuation(const int attenuation)

Set updated attenuation demand on the motion controller.

Calculate positions of individual filters based on a bitmask of the attenuation level, set the parameters on the motion controller and then execute the motion program to move the motors.

The code to set variables through shared memory is inside of an ARM ifdef fence, so when compiled for x86 it will just do the calculations and print a message.

Parameters:

attenuation – [in] Attenuation level to change to [0,15]

void _publish_event(int frame_number)

Publish an event with the given frame number, previous attenuation adjustment and current attenuation.

Parameters:

frame_number – [in] Frame number of event

Private Members

std::string control_channel_endpoint_

Endpoint for control channel

std::string publish_channel_endpoint_

Endpoint for event stream publish channel

std::vector<std::string> subscribe_channel_endpoints_

Endpoints for data message subscribe channels

zmq::context_t zmq_context_

ZMQ Context

zmq::socket_t zmq_control_socket_

ZMQ Socket for control chnanel

zmq::socket_t zmq_publish_socket_

ZMQ Socket for publish chnanel

std::vector<zmq::socket_t> zmq_subscribe_sockets_

ZMQ Socket for subscribe chnanels

ControlState state_

The current logic state

int64_t last_received_frame_

The frame number of the last message that was received, but not necessarily processed - used to determine that the attenuation level is stable in single-shot mode

int64_t last_processed_frame_

The frame number of the last message that was successfully processed - used to decide to ignore some frames

struct timespec last_message_ts_

Time of last message received - not necessarily causing processing

struct timespec last_process_ts_

Time of last process of a message

size_t process_duration_

Duration in microseconds of previous process

size_t process_period_

Time elapsed in microseconds from one process to the next. This will include any time spent waiting for messages and other housekeeping

bool singleshot_start_

Flag to start a new single shot run

std::string shutter_close_string_

The command string to close the shutter

bool clear_error_

Flag to clear error state

bool shutdown_

Flag to interrupt listen loop and shutdown process

std::thread subscribe_thread_

Thread to subscribe to data channel and control filters

int current_attenuation_

Last demanded attenuation to compare against the next attenuation change request

int last_adjustment_

Adjustment from previous frame to publish on the next event

std::vector<int> current_demand_

Filter positions from previous process for calculation of positions after filter in move

std::vector<int> post_in_demand_

Filter positions after filter in move applied

std::vector<int> final_demand_

Filter positions after filter in and out moves applied

int move_duration_

The move duration of the filters in ms

ControlMode mode_

The current mode of operation

float timeout_

Seconds of no messages before setting max attenuation in continuous mode

std::vector<int> in_positions_

Filter in positions in counts (can be +ve or -ve)

std::vector<int> out_positions_

Filter out positions in counts (can be +ve or -ve)

std::map<std::string, uint64_t> pixel_count_thresholds_

Thresholds for histogram bins above which some action should be taken

Enums

enum ControlMode

User demanded mode of control.

Values:

enumerator MANUAL

Ignore data channel and allow manual control of the filters

enumerator CONTINUOUS

Monitor data channel and update attenuation based on configured thresholds

enumerator SINGLESHOT

Continuous until attenuation stablises, pausing at that attenuation until restarted

enumerator CONTROL_MODE_SIZE

Convenience for checking valid value range of ControlMode

enum ControlState

State of internal controller logic.

Values >= 0 are healthy states. Values < 0 are error states.

Values:

enumerator HIGH3_TRIGGERED

Threshold high3 was triggered

enumerator TIMEOUT

Timed out waiting for frames

enumerator IDLE

Ignoring all messages

enumerator WAITING

At max attenuation and waiting for messages

enumerator ACTIVE

Receiving messages and healthy

enumerator SINGLESHOT_WAITING

Waiting for singleshot run

enumerator SINGLESHOT_COMPLETE

Attenuation stablised in singleshot run and waiting for next run

Helper Functions

json _parse_json_string(const std::string &json_string)

Validate and parse json from a string representation to create a json object.

Note even if parse(...) does not throw an exception, the returned json object can be null (empty) and should be tested with .is_null() before access.

Parameters:

json_string – [in] String representation of a json structure

Returns:

json object parsed from string

std::vector<std::string> _parse_endpoints(std::string endpoint_arg)

Parse comma-separated string of endpoints from command line.

Parameters:

endpoint_arg – [in] Comma-separated string of endpoints

Returns:

Vector of endpoints

bool _message_queued(zmq::pollitem_t &pollitem)

Check if a message is queued on the socket corresponding to the pollitem.

If this function returns true, then a recv() on the socket will return a message immediately.

Parameters:

pollitem – [in] zmq_pollitem corresponding to a zmq_socket

Returns:

true if there is a message queued on the socket, else false

bool _is_valid_request(const json &request)

Check if the given json is a valid request.

Parameters:

request – [in] json object of request

Returns:

true if the request is valid, else false

void _get_time(struct timespec *ts)

Get the current time according to the system-wide realtime clock.

Parameters:

ts – [out] Timespec to update with current time

unsigned long _useconds_since(const struct timespec &start_ts)

Return the elapsed time since the given timespec in microseconds.

Parameters:

start_ts – [in] Timespec of start time

Returns:

Microseconds since start time

unsigned long _seconds_since(const struct timespec &start_ts)

Return the elapsed time since the given timespec in seconds.

The time is rounded down to the nearest second

Parameters:

start_ts – [in] Timespec of start time

Returns:

Seconds since start time