# Functions API
# Functions API: General
# debug_message
Print a message in the debug message box within the page.
# Syntax
/**
* @param string $message Message to display
*
* @return void
*/
debug_message($message);
# Example
$x = read_val('FOO');
debug_message('FOO is : ' . $x);
// Output
// 12:24:56(0): FOO is 50000
# info_message
Print a message in the info box within the HMI panel.
# Syntax
/**
* @param string $message Message to display
*
* @return void
*/
info_message('Test info Message Here');
# Example
$x = read_val('FOO');
info_message('FOO is : ' . $x);
# function_active
Return the status of a function (active or inactive) by passing the 3-character ID of the function as a parameter.
# Syntax
/**
* @param string $function_id The function ID
*
* @return bool
*/
function_active('function_id');
# Example
$x = function_active('zxy');
debug_message('Is zxy active? ' . $x);
# device_status
Return device status:
- 0 when device is off or in timeout
- 1 when device is active and responding
# Syntax
/**
* @param string $device Selected device from which to read the status.
*
* @return bool
*/
device_status($device);
# Example
$x = device_status('DEVICE_ONE');
if ($x == 1) {
debug_message('DEVICE IS ON');
} else if ($x == 0) {
debug_message('DEVICE IS OFF');
}
// Output
// 12:24:56(0): DEVICE IS ON
# since_startup
Returns the time elapsed since the system reboot.
The return value can be expressed in:
- seconds => when the function parameter is either 's' or default.
- minutes => when the function parameter is 'm'.
- hours => when the function parameter is'h'.
# Syntax
/**
* @param char $unit specifies the format of the return value.
*
* @return int
*/
since_startup($unit);
# Example
$time = since_startup('s');
debug_message('Elapsed seconds since boot: '.$time);
// Output
// system rebooted at 12:24:51
// 12:24:56(0): Elapsed seconds since boot: 5
# Functions API: Variables
# read_val
Reads a device or a variable and returns its value.
# Syntax
/**
* @param string $var_name
*
* @return number
*/
read_val($device);
# Example
if (read_val('temperature_sensor_1') > 54) {
// do something if the condition is true
debug_message('Temperature Sensor 1 is above 54');
}
// Output
// 12:24:56(0): Temperature Sensor 1 is above 54
# read_future_val
TIP
The variable in question must be registered in the Blackbox to use this function.
Reads a device or a variable X seconds in the future and returns its value.
# Syntax
/**
* @param string $var_name
* @param number $seconds_future
* @return value
*/
read_future_val($var_name, $seconds_future);
# Example
if (read_future_val('temperature_sensor_1', 10) > 54) {
debug_message('Temperature Sensor 1 is above 54, in 10 seconds ahead');
}
// Output
// 12:24:56(0): Temperature Sensor 1 is above 54, in 10 seconds ahead
# write_val
Write the value to a device or a variable.
# Syntax
/**
* @param string $var_name
* @param number $value
*
* @return void
*/
write_val($var_name, $value);
# Example
write_val('temperature_sensor_1', 20);
$x = read_val('temperature_sensor_1');
debug_message('temperature_sensor_1 is ' . $x);
write_val('temperature_sensor_1', 10);
$x = read_val('temperature_sensor_1');
debug_message('temperature_sensor_1 is ' . $x);
// Output
// 12:24:40(0): temperature_sensor_1 is 20
// 12:24:56(0): temperature_sensor_1 is 10
# write_val_period
Write two different values at two distinct time points (defined in milliseconds).
# Syntax
/**
* @param string $var_name
* @param number $value1
* @param number $value2
* @param int $ms1
* @param int $ms2
*/
write_val_period($var_name, $value1, $value2, $ms1, $ms2);
# Example
write_val_period('temperature_sensor_1', 50, -50, 5000, 5000);
// Output
// temperature_sensor_1 will be 50 for the first 5 seconds.
// temperature_sensor_1 will be -50 for the following 5 seconds.
# reset_val_period
Reset the period value set in the write_val_period() function.
# Syntax
/**
* @param string $var_name
*
* @return void
*/
reset_val_period($var_name);
# Example
reset_val_period('temperature_sensor_1');
// Output
// 12:24:40(0): temperature_sensor_1 is 20
# write_val_ramp
Write a value that incrementally increases during a timeframe.
# Syntax
/**
* @param string $var_name
* @param number $rampValueStart
* @param number $rampValueEnd
* @param number $msRampDuration
* @return void
*/
write_val_ramp($var_name, $rampValueStart, $rampValueEnd, $msRampDuration)
WARNING
The generated ramp should be reset after each use.
# Example
write_val_ramp('temperature_sensor_1', 1, 100, 1000);
// Output
// Temperature sensor 1 increases from 1 to 100 in 1000 seconds.
# reset_val_ramp
Reset the ramp associated with the variable.
# Syntax
/**
* @param string $var_name
* @return void
*/
reset_val_ramp($var_name);
# Example
reset_val_ramp('temperature_sensor_1');
// Output
// Temperature sensor stops increasing.
# write_val_at_time
Write a value at the set hour, defined in the format mm:ss.
# Syntax
/**
* @param string $var_name
* @param number $value
* @param string $time
* @return void
*/
write_val_at_time($var_name, $value, $time);
# Example
write_val_at_time('temperature_sensor_1', 100, '16:20')
// Output
// Temperature sensor 1 is updated with the value 100 at 16:20.
# disable
Disable a Device from being written by HMI Panel / Section / Device List.
# Syntax
/**
* @param string $var_name
* @return void
*/
disable($var_name);
# Example
disable('temperature_sensor_1');
// Output
// Temperature sensor 1 cannot be modified from anywhere.
# enable
Enable the Device to be written by HMI Panel / Section / Device List.
# Syntax
/**
* @param string $var_name
* @return void
*/
enable($var_name);
# Example
enable('temperature_sensor_1');
// Output
// Temperature sensor 1 can now be modified.
# get_bounded_value
Return the input value within a limited range.
# Syntax
/**
* @param number $input_value Input value
* @param number $min_value Min value
* @param number $max_value Max value
*
* @return number
*/
get_bounded_value($input_value, $min_value, $max_value);
# Example
get_bounded_value('temperature_sensor_1', 0, 50);
// Output
// The value of Temperature sensor 1 is limited between 0 and 50 degrees.
# is_value_inside_target_range
Return true if the input value is within [target_value - offset; target_value + offset].
If not specified, the offset is 5%.
# Syntax
/**
* @param number $input_value Input value
* @param number $target_value Target value
* @param number $offset Offset to create a range around the target value
*
* @return bool
*/
is_value_inside_target_range($input_value, $target_value, $offset = null);
# Example
/* temperature_sensor_1 = 21 */
is_value_inside_target_range('temperature_sensor_1', 20, 2);
// Output
// The value of temperature sensor 1 is 21, which is less than 22. The function returns true.
# is_value_inside_target_range_mod
Return true if the input value is within the range created by [target_value - offset; target_value + offset], taking into account that the target range can be recalibrated between $input_min and $input_max.
If not specified, the offset is 5% of the target_value.
# Syntax
/**
* @param number $input_value Input value
* @param number $input_min Minimum input value allowed
* @param number $input_max Maximum input value allowed
* @param number $target_value Target value
* @param number $offset Offset to create a range around the target value
*
* @return bool
*/
is_value_inside_target_range_mod($input_value, $input_min, $input_max, $target_value, $offset = null)
# Example
is_value_inside_target_range_mod(980, 0, 1000, 20, 50);
is_value_inside_target_range_mod(980, 0, 1000, 20, 30);
// Output
// The first example returns true because the target range will become [970;1000] union [0;70].
// The second example returns false because the target range will become [990;1000] union [0;50].
# scale_value
Return the scaled value of the input relative to a specified range.
# Syntax
/**
* @param number $input_value Input value
* @param number $input_1 Input range start
* @param number $input_2 Input range end
* @param number $output_1 Output range start
* @param number $output_2 Output range end
* @param bool $round Round to nearest integer
*
* @return number
*/
scale_value($input_value, $input_1, $input_2, $output_1, $output_2, $round = true)
# Example
scale_value(6000, 0, 12000, 0, 3);
// Output
//Since 6000 is exactly half of 12000, the function returns half of 3, which is 2 (rounded to the nearest integer, so 1.5 becomes 2)."
# to_bitmap
Returns a bitmap (integer number) from an array of values (the values are automatically converted to boolean if they are not already boolean in nature).
# Syntax
/**
* @param int[] $values Input array values to be merged into a number (bitmap)
* @param bool $lsb_first If true, array values are considered ordered from LSB to MSB. Else, viceversa.
* @param bool $signed If true, the MSB will be taken with minus sign. Else, viceversa.
*/
to_bitmap($values, $lsb_first = true, $signed = false)
# Example
$bitmap = to_bitmap([1, 0, 1], true);
// the bitmap coversion of the sequence of values [1, 0, 1] is 5.
# from_bitmap
Return an array of bool from bitmap (int).
L'array is populted from the bit less signifiant (LSB) to the bit most significant (MSB): res[0] corrisponds to the compponent 2^0.
# Syntax
/**
* @param int $bitmap Input bitmap
* @param int $length Returned array values length
*/
from_bitmap($bitmap, $length = 16)
# Example
$array = to_bitmap(5, 3);
// Output
//The conversion from the bitmap value 5 returns the vector [1, 0, 1].
# increment_cycling_variable
Increase a system variable and reset it to zero if the new value exceeds $max_value_before_reset.
The updated value is always stored within a variable in the Section: $var_name.
# Syntax
/**
* @param string $var_name Variable to increment
* @param int $max_value_before_reset Max value allowed for storing the new variable value. If the new value goes over this parameter, then variable is reset to $var_reset_value.
* @param int $var_reset_value The value assigned to the variable when it goes over the maximum allowed value.
*
* @return int The updated value
*/
increment_cycling_variable($var_name, $max_value_before_reset, $var_reset_value = 0)
WARNING
The parameter $var_name must be a variable declared within the Sections.
# Example
/* loop_stage = 2 */
increment_cycling_variable('loop_stage', 5, 0);
/* cycle_stage = 5 */
increment_cycling_variable('cycle_stage', 5, 0);
// Output
//The value of loop_stage is incremented by 1 and becomes equal to 3.
//The value of cycle_stage is incremented by 1, but it exceeds the maximum reachable value, so it is reset to 0.
# watchdog_on_bit_inversion
Watchdog control logic for bit inversion: checks for the inversion of a bit within a time window.
If the bit is inverted, a new window starts from the moment of inversion, and the function returns true.
If no inversion occurs, a new window starts, and the function returns false.
The timeout state should always be stored within a section variable: $watchdog_timeout_var.
# Syntax
/**
* @param string $watchdog_timer_name The Plexus timer represents the length of the time window for checking the bit inversion.
* @param string $watchdog_timeout_var The Plexus variable that stores the watchdog state.
* @param bool $watchdog_actual_value The actual value of the bit in the current cycle.
*
* @return bool The timeout state, true when the watchdog has expired.
*/
watchdog_on_bit_inversion($watchdog_timer_name, $watchdog_timeout_var, $watchdog_actual_value)
WARNING
The parameter $watchdog_timeout_var must be a variable declared within the Sections.
# Example
watchdog_on_bit_inversion('watchdog_timer', 'watchdog_timeout', 'watchdog_value');
// Output
// Returns true if the watchdog value changes before the watchdog timer expires.
// Returns false otherwise.
# emergency_status
Returns 1 if the emergency button on the HMI panel is active. Zero otherwise.
# Syntax
emergency_status()
WARNING
The parameter $watchdog_timeout_var must be declared within the Sections.
# Example
if(emergency_status())
debug_message('Emergency is active!');
else
debug_message('Emergency is not active');
// Output
// Returns 1 if the emergency button on the HMI panel is active. Returns 0 otherwise.
# moving_average
Calculate the moving average of a window consisting of X elements (in samples) of the specified variable.
The function can be invoked multiple times with different window lengths.
Each new value is inserted into the window and included in the calculation of the average. As a new value is inserted, the oldest value is removed from the window.
# Syntax
moving_average('var_name', $window_in_samples)
# Example
// loops 0 1 2 3 4
// input 10 20 30 40 30
$media = moving_average('current_mesurament', 4);
echo $media;
// output 10 15 20 25 30
# reset_moving_average
Reset the state of the moving average invoked on the same number of samples.
# Synatax
reset_moving_average('var_name', $window_in_samples)
# Example
reset_moving_average('var_name', 4);
// Output
// Will reset a previous call to moving_average('var_name', 4)
# fixed_average
Calculate the average over a fixed window of X seconds of the specified variable.
# Syntax
fixed_average('var_name', $window_in_seconds)
# Example
// sec 0 1 2 3 4 5 6 7 8 9
// input 10 20 30 40 30 15 20 25 30 40
$media = fixed_average('temperature_values', 4);
echo $media;
// Output
// 0 0 0 0 26 26 26 26 71.25 71.25
# reset_fixed_average
Reset the state of the fixed average invoked on the same period.
# Syntax
reset_fixed_average('var_name', $window_in_seconds)
# Example
reset_fixed_average('var_name', 4);
// Output
// Will reset a previous call to fixed_average('var_name', 4)
# moving_max
Returns the maximum value of a window of X seconds of the specified variable.
Every X seconds, the oldest value is removed.
# Syntax
moving_max('var_name', $window_in_seconds)
# Example
// sec 0 1 2 3 4 5 6 7 8 9
// input 10 20 18 23 17 2 15 7 19 28
$max = moving_max('var_name', 5);
echo $max;
// output 10 20 20 23 23 23 23 17 19 28
# reset_moving_max
Reset the state of the moving max invoked on the same period.
# Syntax
reset_moving_max('var_name', $window_in_seconds)
# Example
reset_moving_max('var_name', 5)
// Output
// Will reset a previous call to moving_max('var_name', 5)
# moving_min
Returns the minimum value of a window of X seconds of the specified variable.
Every X seconds, the oldest value is removed.
# Synatax
moving_min('var_name', $window_in_seconds)
# Example
// sec 0 1 2 3 4 5 6 7 8 9
// input 10 20 18 23 17 2 15 7 19 28
$min = moving_min('var_name', 4);
echo $min;
// output 10 10 10 10 17 2 2 2 2 7
# reset_moving_min
Reset the state of the moving min invoked on the same period.
# Syntax
reset_moving_min('var_name', $window_in_seconds)
# Example
reset_moving_min('var_name', 4)
// Output
// Will reset a previous call to fixed_average('var_name', 4)
# Functions API: Timer
# start_timer
Start Timer
The timer must be previously created in the Sections page.
# Syntax
/**
* @param string $timer_name
* @return void
*/
start_timer($timer_name);
# Example
start_timer('my_timer');
// Output
// `my_timer` will start counting the time.
# reset_timer
Reset the timer.
# Syntax
/**
* @param string $timer_name
* @return void
*/
reset_timer($timer_name);
# Example
reset_timer('my_timer');
// Output
// `my_timer` timer stops counting the time.
# pause_timer
Pause the Timer.
The Timer must have been activated before.
# Syntax
/**
* @param string $timer_name
* @param bool $value (pass 1 to pause it)
* @return void
*/
pause_timer($timer_name, $value);
# Example
pause_timer('my_timer', 1);
// Output
// `my_timer` timer will pause.
# timer_running
Check if the Timer is counting the time.
# Syntax
/**
* @param string $timer_name
* @return bool
*/
timer_running($timer_name);
# Example
if (!timer_running('my_timer')) {
debug_message('TIMER IS NOT RUNNING');
}
// Output
// `TIMER IS NOT RUNNING`
# read_timer
Read the current value of the Timer.
# Syntax
/**
* @param string $timer_name
* @return number
*/
read_timer($timer_name);
# Example
$x = read_timer('my_timer');
debug_message('TIMER IS : ' . $x);
// Output
// `TIMER IS 22000`
# set_timer_duration
Set the duration of the Timer.
# Syntax
/**
* @param string $timer_name
* @param number $duration
* @return void
*/
set_timer_duration($timer_name, $duration);
# Example
set_timer_duration('my_timer', 1000);
// Output
// `my_timer` duration set to 1 second or 1000 milliseconds.
# Functions API: Alerts
# set_alert
Activate an alert with a message.
If this alert is active, it will not trigger the subordinate alarms included in the optional array $subordinated_alarms.
# Syntax
/**
* @param string $alert_name
* @param string $message
* @param Array<string> $subordinated_alarms. Optional, defaults to []
* @return void
*/
set_alert('alert_name', 'message', $subordinated_alarms)
# Example
set_alert('my_alert', 'message', ['subordinated_alarm_name_1', ...])
// Output
// `my_alert` will be activated immediately.
# set_alert_delay
Activate an alert with a message, delayed after msDelay.
If this alert is active, it will not trigger the subordinate alarms included in the optional array $subordinated_alarms.
# Syntax
/**
* @param string $alert_name
* @param string $message
* @param number $msDelay
* @param Array<string> $subordinated_alarms. Optional, defaults to []
* @return void
*/
set_alert_delay('alert_name', 'message', $ms_delay, $subordinated_alarms)
# Example
set_alert_delay('my_alert', 'Something went wrong', $ms_delay, ['subordinated_alarm_name_1', ...])
// Output
// `my_alert` will be activated with a delay of 1 second.
# reset_alert
Reset an alert that has been activated.
# Syntax
/**
* @param string $alert_name
* @return void
*/
reset_alert($alert_name);
# Example
reset_alert('my_alert');
// Output
//`my_alert` will be reset.
# alert_active
Returns the state of an alert, active/inactive.
# Syntax
/**
* @param Alert $alert_name
* @return bool
*/
alert_active($alert_name);
# Example
$x = alert_active('my_alert');
debug_message('my_alert is ' . $x);
// Output
// `my_alert is 1`
# any_alert_active
Returns whether an active alert exists or not.
# Syntax
/**
* @return bool
*/
any_alert_active();
# Example
$x = any_alert_active();
debug_message('Active Alert Currently: ' . $x);
// Output
// `Active Alert Currently: 0`
# Functions API: Stepper API
# start_step
Start the stepper.
# Sintax
/**
* @param string $step_name
* @return void
*/
start_step($stepper);
# Example
start_step('my_stepper');
// Output
// Stepper started
# read_step
Read the stepper
# Syntax
/**
* @param string $step_name
* @return number $value
*/
read_step($step_name);
# Example
$x = read_step('my_stepper');
if ($x == 1) {
debug_message('Step currently at one');
}
// Output
// `1`
# set_step
Set the stepper
# Syntax
/**
* @param string $step_name
* @param number $value
* @return void $value
*/
set_step($step_name, $value);
# Example
set_step('my_step', 10);
if (read_step('my_step') == 10) {
debug_message('Step currently at 10');
}
// Output
// my_step step set to 10.
// Step currently at 10
# Functions API: PID control
# PID_controller
The PID controller aims to keep the controlled process as close as possible to the desired setpoint by minimizing the error and providing a fast and stable response. Please refer to this link (opens new window) for more information on a PID controller.
# Syntax
/**
* @param string $PID_name
* @param Array<string> $PID_params
* "Kd" => number, // Derivative coefficient
* "Kp" => number, // Proportional coefficient (optional, default 0).
* "Ki" => number, // ntegral coefficient (optional, default 0).
* "Measured_Value" => number, // Current measured value
* "Set_Point" => number, // Target value to be reached
* "Set_Point_Max_Error_Tolerance" => number, // Maximum allowable error within which the output is not modified (optional, default = 5% of the Set_Point)
* "Frequency" => int, // Update frequency of the output indicated in number of loops (100ms) (optional, default 1)
* "Measured_Value_Average_Frequency" => int, // Optional, if you want to consider an average value over N samples of Measured_Value instead of the instantaneous value (can be useful in cases where there is noise in the measurement) (optional, default 1)
* "Output_Max" => number, // Maximum output value
* "Output_Min" => number, // Minimum output limit
* "Output_Decimals_Digits" => int, // Number of decimal places to calculate in the output (optional, default 0)
*
* @return number PID output
*/
PID_controller($PID_name, $PID_params)
# Example
PID_controller('my_PID', array(
"Kp" => 0.095,
"Ki" => 0.038,
"Kd" => 0.002,
"Measured_Value" => read_val('pressure_in'),
"Set_Point" => read_val('Pressure_Set_1'),
"Set_Point_Max_Error_Tolerance" => 6,
"Output_Max" => 100,
"Output_Min" => 5,
"Output_Decimals_Digits" => 1
));
# reset_PID_controller
Reset the specified PID controller.
# Syntax
/**
* @param string $PID_name
*/
reset_PID_controller($PID_name)
# Example
reset_PID_controller('PID_name');
// Output
// 'PID_name' verrà resettato
# PWM_controller
It manages the duty cycle of a digital signal with a spicified period. Please refer to this link (opens new window) for more information on Pulse Width Modulation (PWM).
# Syntax
/**
* @param string $PWM_name
* @param int $duty A value from 0 to 100 that indicates the percentage of time within the $msPeriod where the output should be 1.
* @param int $msPeriod The duration of the PWM in milliseconds.
* */
PWM_controller($PWM_name, $duty, $msPeriod)
# Example
PWM_controller('PWM_name', 20, 1000 * 10);
// Output
// 'PWM_name' will be reset
# reset_PWM_controller
Reset the specified PWM controller.
# Syntax
/**
* @param string $PWM_name
*/
reset_PWM_controller($PWM_name)
# Example
reset_PWM_controller('PWM_controller');
// Output
// 'PWM_controller' will be reset
# Include function, example
# Definition of constant
It is useful to define constants in a way that their value is only accessed through their name.
The reference value is changed in a single point in the code
# Syntax
const WEIGHT_GOAL = 7000;
# Example
const WEIGHT_GOAL = 7000;
if (read_val(weight) == WEIGHT_GOAL) { //weight = 7000 kg
debug_message('Goal weight is reached');
}
// Output
// 'Goal weight is reached'
# Definition of enumerated type constants
They can be referenced in the code as: Position::AirFlowing instead of just writing the integer 1, which loses its meaning for someone reading the program
# Syntax
abstract class Position
{
const Unknown = 0;
const Air = 1;
const Load = 2;
const Unload = 3;
}
# Example
if (read_val('Current_position') == Position::Air) {
//Current_position = 1
debug_message('Air position');
}
// Output
// 'Air position'
# Definition of custom API
Define the custom API in the Include section (executed only on the first boot) Set the nozzles to the desired state.
# Syntax
/**
* @param string $status ['open', any other to close]
*/
function set_all_sludge_gates($status)
{
if ($status == 'open') {
write_val('gate_1', 1);
write_val('gate_2', 1);
return;
}
write_val('gate_1', 0);
write_val('gate_2', 0);
}
# Example
set_all_sludge_gates('close');
// Output
// gate_1 closed
// gate_2 closed