StandaloneAutotuning Class Reference

Manages communication and control for an external autotuning process. More...

#include <standalone_autotuning.h>

Public Member Functions
	StandaloneAutotuning (const std::string &programPath, const std::string &host="127.0.0.1")
	Constructs the StandaloneAutotuning instance.
	~StandaloneAutotuning ()
	Destroys the StandaloneAutotuning instance.
bool	start (uint16_t port=kDefaultPort)
	Starts the external autotuning program and waits for its HTTP server to accept requests.
void	stop ()
	Stops the external autotuning process.
bool	isHealthy (unsigned int timeoutMilliseconds=kHealthTimeoutMilliseconds)
	Reports whether the autotuning server is accepting requests.
nlohmann::json	exchange (const nlohmann::json &jsonObj, unsigned int timeoutMilliseconds=kRequestTimeoutMilliseconds)
	Runs a function on the autotuning server and returns its result.
ControllerGains	auto_tune_velocity_controller (const nlohmann::json &data)
	Performs velocity controller autotuning using external autotuning program.
ControllerGains	auto_tune_position_controller (const nlohmann::json &data)
	Performs position controller autotuning using external autotuning program.
FullVelocityAutoTuningResult	full_auto_tune_velocity_controller (const nlohmann::json &data)
	Performs a full velocity controller autotuning sequence using external autotuning program.
FullPositionAutoTuningResult	full_auto_tune_position_controller (const nlohmann::json &data)
	Performs a full position controller autotuning sequence using external autotuning program.
ControllerGains	compute_position_controller_gains (const nlohmann::json &data)
	Computes the position controller gains without performing full autotuning.
PlantModelResult	identify_plant_model (const nlohmann::json &data)
	Identifies the plant model based on the input data.
GeneratePlantBodeFileResult	generate_plant_bode_file (const nlohmann::json &data)
	Computes the bode plot data for the given plant model.

Static Public Attributes
static constexpr uint16_t	kDefaultPort = 63528
	Port the autotuning HTTP server listens on by default.
static constexpr unsigned int	kRequestTimeoutMilliseconds = 120000
	Timeout applied to a function call, in milliseconds.
static constexpr unsigned int	kFitRequestTimeoutMilliseconds = 900000
	Timeout applied to the functions that fit a model, in milliseconds.
static constexpr unsigned int	kHealthTimeoutMilliseconds = 1000
	Timeout applied to a health request, in milliseconds.
static constexpr unsigned int	kReadyTimeoutMilliseconds = 30000
	How long start() waits for the server to accept requests, in milliseconds.

Detailed Description

Manages communication and control for an external autotuning process.

This class starts and stops the external autotuning program and calls its functions over the HTTP API the program exposes with the --http option. It sends JSON requests to POST /api/run and returns the JSON responses, and provides functions for the individual autotuning tasks.

Every call opens its own connection to the server, which serves requests concurrently, so the calls may be made from any thread.

Constructor & Destructor Documentation

StandaloneAutotuning()

StandaloneAutotuning::StandaloneAutotuning ( const std::string & programPath, const std::string & host = "127.0.0.1" )

explicit

Constructs the StandaloneAutotuning instance.

Parameters

programPath	Path to the external autotuning program executable.
host	Address the program's HTTP server is told to bind to.

The constructor only records where the server will be; no process is started and no connection is made until start() is called. The port is given to start(), because an instance may well be constructed before the command line that carries the port has been parsed.

~StandaloneAutotuning()

StandaloneAutotuning::~StandaloneAutotuning

(

)

Destroys the StandaloneAutotuning instance.

This destructor stops the autotuning process by calling the stop() method. It ensures proper cleanup of resources when the object is destroyed.

Member Function Documentation

auto_tune_position_controller()

ControllerGains StandaloneAutotuning::auto_tune_position_controller

(

const nlohmann::json &

data

)

Performs position controller autotuning using external autotuning program.

Parameters

data	Input data for the autotuning process, typically containing the necessary parameters for tuning.

Returns

The computed ControllerGains for the position controller.

Exceptions

std::runtime_error

If the response is empty, null, or does not contain the expected 'gains' field.

This method constructs a JSON object with the autotuning command and input data, sends it to the external autotuning program, and waits for the response. If the response is valid and contains the 'gains' field, it parses and returns the ControllerGains. If the response is invalid or the 'gains' field is missing, an error is logged and an exception is thrown.

auto_tune_velocity_controller()

ControllerGains StandaloneAutotuning::auto_tune_velocity_controller

(

const nlohmann::json &

data

)

Performs velocity controller autotuning using external autotuning program.

Parameters

data	Input data for the autotuning process, typically containing the necessary parameters for tuning.

Returns

The computed ControllerGains for the velocity controller.

Exceptions

std::runtime_error

If the response is empty, null, or does not contain the expected 'gains' field.

This method constructs a JSON object with the autotuning command and input data, sends it to the external autotuning program, and waits for the response. If the response is valid and contains the 'gains' field, it parses and returns the ControllerGains. If the response is invalid or the 'gains' field is missing, an error is logged and an exception is thrown.

compute_position_controller_gains()

ControllerGains StandaloneAutotuning::compute_position_controller_gains

(

const nlohmann::json &

data

)

Computes the position controller gains without performing full autotuning.

Parameters

data	Input data for computing the position controller gains, typically containing parameters related to the system.

Returns

The computed position controller gains, encapsulated in ControllerGains.

Exceptions

std::runtime_error

If the response is empty, null, or does not contain the expected 'gains' field.

This method constructs a JSON object with the command to compute position controller gains and the input data, sends it to the external autotuning program, and waits for the response. If the response contains the computed gains, it returns them in the form of a ControllerGains object. If the response is invalid or does not contain the expected 'gains', an error is logged and an exception is thrown.

exchange()

nlohmann::json StandaloneAutotuning::exchange	(	const nlohmann::json &	jsonObj,
		unsigned int	timeoutMilliseconds = kRequestTimeoutMilliseconds )

Runs a function on the autotuning server and returns its result.

Parameters

jsonObj	The request body, a JSON object with a run property naming the function and a data property holding its inputs.
timeoutMilliseconds	The timeout in milliseconds for the request.

Returns

The JSON response received from the server.

A function that rejects its inputs reports that as an error property in an otherwise successful response, which is turned into an exception here. Responses that carry bode data in a bode property are given an additional bode_file_content property holding the same data in CSV form, which is the shape clients consume.

Exceptions

std::runtime_error

If the server cannot be reached, the request times out, or the response reports an error.

full_auto_tune_position_controller()

FullPositionAutoTuningResult StandaloneAutotuning::full_auto_tune_position_controller

(

const nlohmann::json &

data

)

Performs a full position controller autotuning sequence using external autotuning program.

Parameters

data	Input data for the autotuning process, typically containing the necessary parameters for tuning.

Returns

The detailed results of the full position autotuning, encapsulated in FullPositionAutoTuningResult.

Exceptions

std::runtime_error

If the response is empty, null, or cannot be parsed into the expected result.

This method constructs a JSON object with the autotuning command and input data, sends it to the external autotuning program, and waits for the response. If the response is valid and can be parsed into a FullPositionAutoTuningResult, it returns the result. If the response is invalid or empty, an error is logged and an exception is thrown.

full_auto_tune_velocity_controller()

FullVelocityAutoTuningResult StandaloneAutotuning::full_auto_tune_velocity_controller

(

const nlohmann::json &

data

)

Performs a full velocity controller autotuning sequence using external autotuning program.

Parameters

data	Input data for the autotuning process, typically containing the necessary parameters for tuning.

Returns

The detailed results of the full velocity autotuning, encapsulated in FullVelocityAutoTuningResult.

Exceptions

std::runtime_error

If the response is empty, null, or cannot be parsed into the expected result.

This method constructs a JSON object with the autotuning command and input data, sends it to the external autotuning program, and waits for the response. If the response is valid and can be parsed into a FullVelocityAutoTuningResult, it returns the result. If the response is invalid or empty, an error is logged and an exception is thrown.

generate_plant_bode_file()

GeneratePlantBodeFileResult StandaloneAutotuning::generate_plant_bode_file

(

const nlohmann::json &

data

)

Computes the bode plot data for the given plant model.

Parameters

data	JSON object containing the plant model input parameters.

Returns

GeneratePlantBodeFileResult object holding the bode plot data in CSV form.

Exceptions

std::runtime_error

If the response is empty, null, or contains an error.

identify_plant_model()

PlantModelResult StandaloneAutotuning::identify_plant_model

(

const nlohmann::json &

data

)

Identifies the plant model based on the input data.

Parameters

data	Input data for plant model identification: the chirp measurements in a csv property, plus the f0 and f1 chirp frequencies.

Returns

A PlantModelResult object containing the identified plant model's numerators and denominators as vectors of doubles, along with the bode plot data in CSV form.

Exceptions

std::runtime_error

If the response is empty, null, or does not contain the expected 'numerators' or 'denominators' fields.

The measurements travel in the request body, so the server needs no access to the file they were written to.

isHealthy()

bool StandaloneAutotuning::isHealthy

(

unsigned int

timeoutMilliseconds = kHealthTimeoutMilliseconds

)

Reports whether the autotuning server is accepting requests.

Parameters

timeoutMilliseconds

Timeout for the health request.

Returns

True if GET /api/health responded with a status of "ok".

start()

bool StandaloneAutotuning::start

(

uint16_t

port = kDefaultPort

)

Starts the external autotuning program and waits for its HTTP server to accept requests.

Parameters

port	Port the program's HTTP server is told to listen on.

Returns

True if the process started and the server became ready, false otherwise.

The program is started with the --http, --host and --port options, so that it serves the autotuning functions instead of running a single one and exiting. Its output is discarded.

On Windows, a job object is created to manage the child process and ensure it is terminated if the parent process is forcibly terminated. This is necessary because when the Electron main process sends a kill signal on Windows, it forcefully terminates the parent process without notifying the child process or allowing it to shut down properly. Without the job object, the child process would remain running in the background.

The program unpacks itself before it starts serving, so start() polls GET /api/health until it responds, giving up after kReadyTimeoutMilliseconds or as soon as the process is seen to have died.

stop()

void StandaloneAutotuning::stop

(

)

Stops the external autotuning process.

Asks the server to shut itself down with an exit request, then terminates the process if it is still running.

Member Data Documentation

kDefaultPort

uint16_t StandaloneAutotuning::kDefaultPort = 63528

staticconstexpr

Port the autotuning HTTP server listens on by default.

kFitRequestTimeoutMilliseconds

unsigned int StandaloneAutotuning::kFitRequestTimeoutMilliseconds = 900000

staticconstexpr

Timeout applied to the functions that fit a model, in milliseconds.

System identification and full autotuning scale steeply with the number of recorded samples: a 5000-sample recording is identified in a fraction of a second, while a 96000-sample one measured just under two minutes. The ceiling is here to end a wedged request eventually, not to bound a legitimate computation, so it is far above what either needs.

kHealthTimeoutMilliseconds

unsigned int StandaloneAutotuning::kHealthTimeoutMilliseconds = 1000

staticconstexpr

Timeout applied to a health request, in milliseconds.

kReadyTimeoutMilliseconds

unsigned int StandaloneAutotuning::kReadyTimeoutMilliseconds = 30000

staticconstexpr

How long start() waits for the server to accept requests, in milliseconds.

kRequestTimeoutMilliseconds

unsigned int StandaloneAutotuning::kRequestTimeoutMilliseconds = 120000

staticconstexpr

Timeout applied to a function call, in milliseconds.

Generous, because a full autotuning run performs an optimization that takes considerably longer than the request itself.

---

The documentation for this class was generated from the following files:

• libs/standalone_autotuning/standalone_autotuning.h
• libs/standalone_autotuning/standalone_autotuning.cc