Brewblox

# Sequence block instructions

reference manual for supported instructions.

# Line protocol

Unlike other block data fields, Sequence instructions are not represented as JSON object, but as a line protocol. The intention is that end users can easily read and edit the line protocol.

The basic syntax for instructions is:

OPCODE arg1=value, arg2=value ...

Any instruction will always have an opcode, and zero or more arguments. All arguments must always be present.

Arguments use a comma-separated key=value syntax, and do not have to be listed in any particular order. There is no comma between the opcode and the first argument.

If an instruction has arguments, they are separated from the opcode with at least one space. Any number of spaces can be inserted next to the comma , and = separator characters.

Both instructions in the below example are equally valid.

OPCODE key1=value,key2=value
OPCODE      key1   =  value  ,   key2   = value

Quantities are automatically identified, and converted where required. The output from the Spark service always returns quantities with the user-preferred units.
Abbreviated temperature units are used: C or F for absolute values, and dC or dF for relative values.

Time duration values (such as found in WAIT_DURATION) can be expressed either in integer seconds, or as duration string (eg. 1d6h10m5s).

If any argument is a string that contains trailing or leading spaces, it must be quoted using single quotes. For all other arguments, quotes are allowed but optional.

Lines that start with a # are comments, and will not be executed. Comments are stored on the Spark, and may cause it to run out of memory.

Example instructions:

SET_SETPOINT target=BK Setpoint, setting=65C
ENABLE target='BK Setpoint'
WAIT_SETPOINT target='BK Setpoint', precision=1dC
# Starting the profile sets its start time to 'now'
START_PROFILE target='BK Profile '
ENABLE target='BK Profile'
WAIT_PROFILE target='BK Profile '

# Block interfaces

Instructions that have a target block may require a block that implements a specific interface, and not a single block type.

export const COMPATIBLE_TYPES: Record<BlockIntfType, BlockType[]> = {
  Any: Enum.values(BlockType),
  ProcessValueInterface: [
    BlockType.ActuatorAnalogMock,
    BlockType.ActuatorOffset,
    BlockType.ActuatorPwm,
    BlockType.FastPwm,
    BlockType.SetpointSensorPair,
  ],
  TempSensorInterface: [
    BlockType.TempSensorCombi,
    BlockType.TempSensorExternal,
    BlockType.TempSensorMock,
    BlockType.TempSensorOneWire,
  ],
  SetpointSensorPairInterface: [BlockType.SetpointSensorPair],
  ActuatorAnalogInterface: [
    BlockType.ActuatorAnalogMock,
    BlockType.ActuatorOffset,
    BlockType.ActuatorPwm,
    BlockType.FastPwm,
  ],
  ActuatorDigitalInterface: [BlockType.DigitalActuator, BlockType.MotorValve],
  DigitalInterface: [
    BlockType.DigitalActuator,
    BlockType.MotorValve,
    BlockType.DigitalInput,
  ],
  BalancerInterface: [BlockType.Balancer],
  MutexInterface: [BlockType.Mutex],
  OneWireBusInterface: [BlockType.OneWireGpioModule],
  OneWireDeviceInterface: [
    BlockType.TempSensorOneWire,
    BlockType.DS2408,
    BlockType.DS2413,
  ],
  IoModuleInterface: [],
  IoArrayInterface: [
    BlockType.DS2408,
    BlockType.DS2413,
    BlockType.Spark2Pins,
    BlockType.Spark3Pins,
    BlockType.OneWireGpioModule,
    BlockType.MockPins,
  ],
  IoDriverInterface: [
    BlockType.DigitalActuator,
    BlockType.MotorValve,
    BlockType.FastPwm,
    BlockType.DigitalInput,
  ],
  DS2408Interface: [BlockType.DS2408],
  EnablerInterface: [
    BlockType.ActuatorAnalogMock,
    BlockType.ActuatorOffset,
    BlockType.ActuatorLogic,
    BlockType.Pid,
    BlockType.Sequence,
    BlockType.ActuatorPwm,
    BlockType.FastPwm,
    BlockType.SetpointSensorPair,
    BlockType.SetpointProfile,
    BlockType.TempSensorExternal,
  ],
  ClaimableInterface: [
    BlockType.ActuatorAnalogMock,
    BlockType.ActuatorOffset,
    BlockType.ActuatorPwm,
    BlockType.DigitalActuator,
    BlockType.FastPwm,
    BlockType.MotorValve,
    BlockType.SetpointSensorPair,
  ],
};

# Error states

The Sequence block will enter an error state if invalid configuration or system state is detected. If the error is resolved (for example, by creating a missing target), the error state is cleared automatically.

  • INVALID_TARGET: The target block does not exist, or is the wrong type.
  • INACTIVE_TARGET: The target block is inactive because it depends on or is driven by a block that is missing, disabled or disconnected.
  • DISABLED_TARGET: The target block is disabled in configuration.
  • SYSTEM_TIME_NOT_AVAILABLE: Controller system time is not set, and the Sequence block can't execute any instructions.
export const SequenceError = Enum(
  'NONE',
  'INVALID_ARGUMENT',
  'INVALID_TARGET',
  'INACTIVE_TARGET',
  'DISABLED_TARGET',
  'SYSTEM_TIME_NOT_AVAILABLE',
);

# Instructions

Below is a list of supported opcodes, their arguments, and the errors they may trigger. The SYSTEM_TIME_NOT_AVAILABLE error is not listed, as it is triggered before any instruction is executed.

RESTART

When this instruction is executed, the Sequence jumps back to the first instruction. Any instructions after the RESTART will not be executed.

Arguments

N/A

Errors

N/A

Example
RESTART

ENABLE

Sets the enabled field for given block to true.

Arguments
  • target: block ID (EnablerInterface)
Errors
  • INVALID_TARGET
Example
ENABLE target='Fridge Setting'

DISABLE

Sets the enabled field for the given block to false.

Arguments
  • target: block ID (EnablerInterface)
Errors
  • INVALID_TARGET
Example
DISABLE target='Fridge Setting'

WAIT

Waits until the user manually skips to the next instruction.

Arguments

N/A

Errors

N/A

Example
WAIT

WAIT_DURATION

Waits until a given duration has elapsed since the instruction was started. If the *Sequence* is disabled while this instruction is active, time spent disabled is **not** included. If the controller is shut down while this instruction is active, time spent shut down is included.

Arguments
  • duration: duration (Duration string or integer seconds)
Errors

N/A

Example
WAIT_DURATION duration=1h10m5s

WAIT_UNTIL

Waits until current time is later than time argument.

Arguments
  • time: timestamp (ISO-8601 string)
Errors
  • SYSTEM_TIME_NOT_AVAILABLE
Example
WAIT_UNTIL time=2022-07-25T18:13:50Z

WAIT_TEMP_BETWEEN

Waits until the measured value of target temperature sensor is inside a temperature range.

Arguments
  • target: block ID (TempSensorInterface)
  • lower: target value must be above this temperature (Temperature)
  • upper: target value must be below this temperature (Temperature)
Errors
  • INVALID_TARGET
  • INACTIVE_TARGET
Example
WAIT_TEMP_BETWEEN target='Fridge Sensor', lower=1C, upper=5C

WAIT_TEMP_NOT_BETWEEN

Waits until the measured value of target temperature sensor is outside a temperature range. The sensor must be connected and readable for this instruction to finish.

Arguments
  • target: block ID (TempSensorInterface)
  • lower: target value must be below this temperature (Temperature)
  • upper: target value must be above this temperature (Temperature)
Errors
  • INVALID_TARGET
  • INACTIVE_TARGET
Example
WAIT_TEMP_NOT_BETWEEN target='Fridge Sensor', lower=1C, upper=5C

WAIT_TEMP_UNEXPECTED

Waits until the measured value of target temperature sensor is unreadable or outside a temperature range. Compared to WAIT_TEMP_NOT_BETWEEN, this condition is more suitable for alerts, as it will not cause an error state if the sensor is disconnected.

Arguments
  • target: block ID (TempSensorInterface)
  • lower: target value must be below this temperature (Temperature)
  • upper: target value must be above this temperature (Temperature)
Errors
  • INVALID_TARGET
Example
WAIT_TEMP_UNEXPECTED target='Fridge Sensor', lower=1C, upper=5C

WAIT_TEMP_ABOVE

Waits until the measured value of target temperature sensor is above a given value. The sensor must be connected and readable for this instruction to finish.

Arguments
  • target: block ID (TempSensorInterface)
  • value: target value must be above this temperature (Temperature)
Errors
  • INVALID_TARGET
  • INACTIVE_TARGET
Example
WAIT_TEMP_ABOVE target='Fridge Sensor', value=1C

WAIT_TEMP_BELOW

Waits until the measured value of target temperature sensor is below a given value. The sensor must be connected and readable for this instruction to finish.

Arguments
  • target: block ID (TempSensorInterface)
  • value: target value must be below this temperature (Temperature)
Errors
  • INVALID_TARGET
  • INACTIVE_TARGET
Example
WAIT_TEMP_BELOW target='Fridge Sensor', value=5C

SET_SETPOINT

Sets the desired setting of a Setpoint block.

Arguments
  • target: block ID (SetpointSensorPair)
  • setting: new desired setting for target block (Temperature)
Errors
  • INVALID_TARGET
Example
SET_SETPOINT target='Fridge Setting', setting=40F

WAIT_SETPOINT

Waits until the measured value of a *Setpoint* block is close enough to its desired setting. The precision argument is not centered on the desired setting: the instruction will finish if either value >= setting - precision or value <= setting + precision is true.

Arguments
  • target: block ID (SetpointSensorPair)
  • precision: Acceptable delta between setpoint setting and value (Delta Temperature)
Errors
  • INVALID_TARGET
  • DISABLED_TARGET
  • INACTIVE_TARGET
Example
WAIT_SETPOINT target='Fridge Setting', precision=0.1dC

WAIT_SETPOINT_ABOVE

Waits until the measured value of a *Setpoint* block is more than its desired setting + precision.

Arguments
  • target: block ID (SetpointSensorPair)
  • precision: Dead band between setpoint setting and condition trigger (Delta Temperature)
Errors
  • INVALID_TARGET
  • DISABLED_TARGET
  • INACTIVE_TARGET
Example
WAIT_SETPOINT_ABOVE target='Fridge Setting', precision=0.1dC

WAIT_SETPOINT_BELOW

Waits until the measured value of a *Setpoint* block is less than its desired setting - precision.

Arguments
  • target: block ID (SetpointSensorPair)
  • precision: Dead band between setpoint setting and condition trigger (Delta Temperature)
Errors
  • INVALID_TARGET
  • DISABLED_TARGET
  • INACTIVE_TARGET
Example
WAIT_SETPOINT_BELOW target='Fridge Setting', precision=0.1dC

SET_DIGITAL

Sets the desired setting of target Digital Actuator.

Arguments
  • target: block ID (DigitalActuator)
  • setting: desired state (STATE_INACTIVE | STATE_ACTIVE)
Errors
  • INVALID_TARGET
Example
SET_DIGITAL target='Cool Actuator', setting=STATE_ACTIVE

WAIT_DIGITAL

Waits until the state of the target Digital Actuator matches its desired state.

Arguments
  • target: block ID (DigitalActuator)
Errors
  • INVALID_TARGET
Example
WAIT_DIGITAL target='Cool Actuator'

WAIT_DIGITAL_EQUALS

Waits until the state of target Digital Input or Digital Actuator matches a given state

Arguments
  • target: block ID (DigitalInterface)
  • state: target state must be equal to this (STATE_INACTIVE | STATE_ACTIVE)
Errors
  • INVALID_TARGET
Example
WAIT_DIGITAL_EQUALS target='Cool Actuator', state=STATE_ACTIVE

SET_PWM

Sets the desired setting of target PWM block.

Arguments
  • target: block ID (ActuatorAnalogInterface)
  • setting: desired setting percentage (Number 0-100)
Errors
  • INVALID_TARGET
Example
SET_PWM target='Cool PWM', setting=50

START_PROFILE

(Re)starts a target Setpoint Profile block by setting its start field to the date and time at which this instruction is executed. The target block enabled state is not changed. To start a disabled Profile, the ENABLE and START_PROFILE instructions should be used in combination.

Arguments
  • target: block ID (SetpointProfile)
Errors
  • INVALID_TARGET
  • SYSTEM_TIME_NOT_AVAILABLE
Example
START_PROFILE target='Fridge Profile'
ENABLE target='Fridge Profile'

WAIT_PROFILE

Waits until the last point is reached in target Setpoint Profile block.

Arguments
  • target: block ID (SetpointProfile)
Errors
  • INVALID_TARGET
  • DISABLED_TARGET
  • SYSTEM_TIME_NOT_AVAILABLE
Example
WAIT_PROFILE target='Fridge Profile'

START_SEQUENCE

(Re)starts a target Sequence block by setting its activeInstruction field to 0. The target block enabled state is not changed. To start a disabled Sequence, the ENABLE and START_SEQUENCE instructions should be used in combination.

Arguments
  • target: block ID (Sequence)
Errors
  • INVALID_TARGET
Example
START_SEQUENCE target='Mash Sequence'
ENABLE target='Mash Sequence'

WAIT_SEQUENCE

Waits until the target Sequence has reached the END state. A Sequence that includes a RESTART instruction will never reach an END state.

Arguments
  • target: block ID (Sequence)
Errors
  • INVALID_TARGET
  • DISABLED_TARGET
Example
WAIT_SEQUENCE target='Mash Sequence'

← Introduction →