Skip to content

Latest commit

 

History

History
88 lines (67 loc) · 5.7 KB

parameters.rst

File metadata and controls

88 lines (67 loc) · 5.7 KB
Raw

Parameters

Table of contents

Parameters can be used to capture or influence the current state of the spacecraft or your app. In the case of our example app, the parameters will be the gains for the RGB colour channels and the exposure time of the camera.

Defining parameters

Internally, parameters are most likely just Java attributes of your app or provided by some other service. So to define our available parameters, we just need to define them in our class:

private float gainR = 4.0f;
private float gainG = 4.0f;
private float gainB = 4.0f;
private float exposureTime = 0.2f;

Registering parameters

To register the parameters we need to add the @Parameter annotation to the previously defined variables. This annotation has the following arguments:

  • String name - The name of the parameter. If the value is not provided the name of the variable will be used.
  • String description - The description of the parameter. Empty by default.
  • String malType - The MAL type of the parameter. This is auto generated by default if the variable's type is an Attribute (like UInteger, UShort etc.) or a built in java type (int, double, String etc.).
  • String rawUnit - The raw unit of the parameter. For example: rad, m/s. Empty by default.
  • boolean generationEnabled - Specifies if the generation of the parameter should be enabled. True by default.
  • double reportIntervalSeconds - Specifies how often the parameter will be reported (in seconds). By default it's set to 0 which disables automatic generation.
  • String validityExpressionFieldName - Name of the field containing a ParameterExpression instance containing the validity expression for this parameter. Empty by default.
  • String conversionFunctionName - Name of the field containing a ParameterConversion instance containing the conversion for this parameter. Empty by default.
  • boolean readOnly - Specifies it the parameter should be read only. If the variable is final the parameter will always be read only. False by default.
  • boolean restored - Specifies if the value of the parameter should be restored to the last known value on application startup. True by default.
  • String onGetFunction - The name of the function that will be called every time before the parameter value is read. This function can't have any arguments and all return values are ignored. It is required that this function is public. Empty by default.
  • String[] aggregations - List of aggregation names this parameter belongs to. Empty by default.

The previously defined variables with the annotation will look like this:

@Parameter(description = "Camera red channel gain", generationEnabled = false, reportIntervalSeconds = 10, onGetFunction = "onGetGainR")
private float gainR = 4.0f;
@Parameter(description = "Camera green channel gain", generationEnabled = false, reportIntervalSeconds = 10, onGetFunction = "onGetGainG")
private float gainG = 4.0f;
@Parameter(description = "Camera blue channel gain", generationEnabled = false, reportIntervalSeconds = 10, onGetFunction = "onGetGainB")
private float gainB = 4.0f;
@Parameter(description = "Camera exposure time", generationEnabled = false, reportIntervalSeconds = 10, onGetFunction = "onGetExposureTime")
private float exposureTime = 0.2f;

All the parameters that have the annotation will be automatically registered in the initialRegistrations function from the MonitorAndControlNMFAdapter. If the initialRegistrations function is overriden it is important to call super.initialRegistrations(registration) to make sure the parameters are registered.

Getting the value of a parameter

If you provided the onGetFunction parameter in the registration annotation. You need to implement the specified function in your adapter. Example function for the gainR parameter could look like this:

public void onGetGainR() {
  gainR = getNewGainR() // somehow get the new value - for example query it from the on board camera.
}

This onGetGainR function will be called every time before the parameter value is read. After the function finishes executing the newly updated value will be sent.

If the parameter is registered without the onGetFunction then the current value of the field will be sent.

Setting the value of a parameter

To set the value of a parameter there is no need to implement anything. You just need to call setValue from the Parameter service. Setting of the values is handled automatically in the onSetValue function from the MonitorAndControlNMFAdapter. If you want some special behavior during parameter setting you can override the onSetValue function in your adapter.

Summary

We are now able to use parameters in our app! Here is just a quick recap of what you need to do in order to use parameters:

  1. Declare some variables that hold your parameters values and provide a default value.
  2. Register your parameters using the @Parameter annotation.
  3. Implement onGetFunction for each parameter that specifies it.

We only covered the basics of parameter handling. There is even more stuff that you can do with them (e.g. updating parameter values on a regular basis)! If you want to learn about this, check out the Publish Clock Example on GitHub.

Now that our parameters are ready to go, it is time to implement some actions.