Edge program starters

A starter is a ready-made edge program for a common task on an MC252, with a few fields to fill in: the parameters it reads and writes, levels, times and file name. It builds an ordinary program that opens unsaved in the Programs tab’s editor, where you review it and save it; nothing is created before you save. After that it is your program: change it like any other, and later changes to the starter do not touch it.

To use one, see start from a starter.

What every starter does

• It runs without the cloud. The program decides on the device; HMI only shows and adjusts it.
• Inputs and outputs are parameters of devices behind the MC252. The MC252 has no inputs or outputs of its own, so a field takes a Modbus parameter of the same endpoint. The program reads and writes its register directly, with the parameter’s scaling: levels and limits are entered in the parameter’s units. A parameter with a formula, BCD, bit fields, single bytes or a zero or negative multiplier cannot be read by a program, and the form says so. An on/off parameter in one bit of one, two or four registers, such as a relay bit of a status register, can be read but not written. A program writes an output of more than one register in one request, so an output with the single-write write function must be one register.
• Hysteresis control, the astronomical timer and the weekly timer switch their output one of two ways, chosen under Output control: an on/off parameter written 1 and 0 (Output), or command codes. With codes, the program writes the Switch-on code or Switch-off code to the Command parameter and reads whether the output is on from Output state, an on/off parameter. Use codes for devices whose relays switch by a command register, where writing 1 may mean something else, such as a restart. Codes are in the command parameter’s units and within its write limits.
• An unknown input leads to a defined state. A read that fails, or a value the device reports as unavailable (the parameter’s unavailable value), counts as unknown; each starter says what it then does. A failed write is tried again on the next run.
• Outputs are written only when they differ from what the output holds, so other writers are not fought every run.
• A device that does not answer delays every program of the controller, which runs one program at a time: starters give each read or write at most 1 s instead of the device’s 5 s.
• Times are on the device clock, in its time zone with daylight saving time; set the clock and, for the astronomical timer, the location on the device.
• The file name is the starter’s suggestion, numbered when the device already has one by that name. It sets the load order.

Values shared with HMI

Some starters keep values in the device’s battery-backed memory and show them in its own holding registers from 5000 up, at the first registers no other program of the device maps. Saving such a program also adds a parameter for each one, on the MC252’s own unit (the Controller unit ID field, 111 unless changed on the device), in the branch you choose. HMI writes them one register at a time, which the device accepts without register access rights.

Battery-backed memory is small (64 bytes for all programs of a device) and is laid out in load order. When programs before this one are added, removed or changed, its values may move. Each such starter keeps a check word and starts from its initial values when the check word is wrong, so a moved value is never taken for its own: counters restart from zero and levels and setpoints return to the values the program was built with.

Starters

Periodic logging

Records parameters to the device log every few minutes, also while the device is offline. HMI imports the records as the parameters’ history; see record readings on the device.

Field	Meaning
Record every	1 min to 24 h (10 min)
Parameters, Comment	Up to 20 parameters; an optional ASCII comment stored with each record in CSV

When a parameter cannot be read it is skipped for that record; the others are still recorded. Records go to the device’s microSD card whether Device logging is on or off; that setting only covers SYSLOG output and run-time errors. The program logs device registers, never its own memory, which would stop all logging on the device.

Hysteresis control

Switches an output on at one level and off at another, like a thermostat or a level switch.

Field	Meaning
Measured value	A number parameter
Output control, Output	A writable on/off parameter (a coil, or a register written 1 and 0), or command codes
Output effect	Raises the value (on below the switch-on level) or lowers it (on above it)
Switch-on, switch-off level	The two levels; between them the output stays as it is
While the value is unknown	Switch the output off (default) or on
Run every	1 s to 1 h (5 s)
Adjustable from dashboards	Adds both levels as parameters, kept in battery-backed memory
Name, Add parameters to	Shown with adjustable levels: the parameters’ names (Boiler switch-on level) and their branch

When the value is unknown the output is written to the chosen state, or sent its code, every run until a reading comes back. The same happens while the output state cannot be read or is unknown. Adjustable levels that are missing, or in the wrong order for the direction, are not used: the levels the program was built with apply until both fit again.

Duty/standby alternation on the device

Runs one of two to four pumps or fans at a time and hands duty on to the next.

Field	Meaning
Units: Run command, Fault	Per unit, in duty order: a writable on/off command and an optional fault input
Run request	Optional on/off input: the duty unit runs while it is on; without it, always
While the run request is unknown	Shown with a run request: stop all units (default) or run the duty unit
Hand duty on after	A number of starts (needs a run request), or of running hours
Starts or hours per unit	1 to 1000 (24)
Run every	1 s to 1 h (5 s)

Builds a program that switches the duty unit’s command on while it should run and every other command off, switching commands off before it switches one on. By starts, duty passes on at the start after the count; by hours, while running.

When a unit fails — its fault is on, its fault cannot be read, or its command could not be written — duty passes to the next healthy unit at once; a recovered unit does not take duty back. With no healthy unit, every command is switched off. A unit whose command cannot be switched off does not hold back the next one: both may run until the stop gets through, which the program tries on every run. After a restart of the controller, unit 1 has duty and counts start again.

Astronomical timer

Switches an output on at sunset and off at sunrise, for lighting.

Field	Meaning
Output control, Output	A writable on/off parameter, or command codes
Switch on after sunset	Minutes, −240 to 240; negative switches on before sunset
Switch off after sunrise	Minutes, −240 to 240; negative switches off before sunrise
Night pause from, until	Optional: the output stays off between these times, such as 01:00 to 05:00

Sunrise and sunset come from the location set on the device (Administration → Astronomical Settings in its web interface). In polar night the output stays on; in polar day, off. The program checks every 30 s.

Weekly timer

Switches an output on and off at set times on chosen weekdays.

Field	Meaning
Output control, Output	A writable on/off parameter, or command codes
On periods: Days, On, Off	Up to 14 periods; no day chosen means every day

The output is on while any period is. A period that ends before it starts runs past midnight into the next day: Friday 22:00 to 02:00 ends on Saturday at 02:00. The program checks every 30 s.

Threshold alarm by SMS

Sends an SMS from the device’s own modem when a value stays above or below a limit.

Field	Meaning
Value, Alarm when the value is, Limit	A number parameter, above or below the limit
Clears this far back	The alarm clears once the value is back past the limit by this much (0)
Alarm after	How long the value must stay past the limit, 0 s to 1 h (60 s)
At most one alarm SMS per	1 min to 24 h (60 min): an alarm within this time of the last alarm SMS sends none
Send to	Up to four numbers (+48123456789), or #1 to #4 for the device’s own phone list
Alarm SMS	The message, up to 127 Latin letters, digits and punctuation; * counts twice
Cleared SMS	Optional: sent when an alarm that sent an SMS clears
No reading SMS	Optional: the alarm also raises, with this message, when the value stays unreadable

When the value is unknown without a No reading SMS, the alarm stays as it is. An SMS that cannot be sent, such as without network, is skipped and does not stop the program. The device needs a working SIM card; the alarm state restarts when the controller does.

Run hours and start counter

Counts how long a machine runs and how often it starts.

Field	Meaning
Running signal	An on/off input, on while the machine runs
Name, Add parameters to	The parameters’ names (Pump 1 run hours, Pump 1 starts) and branch
Controller unit ID	The MC252’s own Modbus unit ID (111)

Builds two values in battery-backed memory, run time in seconds and the number of starts, and adds them as parameters: run hours with one decimal, and starts. Write 0 to either to reset it.

When the signal cannot be read nothing is counted, and a run seen when it comes back is not counted as a start; nor is one first seen after a restart. The program counts every 10 s, so up to about 10 s of run time can be lost at a power cut.

Setpoint adjustable from dashboards

Keeps a setpoint that dashboards write, and passes it on to a device register, such as a drive’s speed reference or a controller’s setpoint.

Field	Meaning
Device setpoint	A writable number parameter the program writes the setpoint to
Name	The name of the setpoint parameter dashboards write
Lowest, Highest	The limits: HMI refuses writes outside them, and the program brings a setpoint another writer put outside them back to the nearest
Initial setpoint	Used until one is written, and again when battery-backed memory is lost
Run every	1 s to 1 h (5 s)
Add parameters to, Controller unit ID	Where the setpoint parameter goes, and the MC252’s own unit ID

Builds a setpoint in battery-backed memory, added as a parameter with the device setpoint’s units and the limits as its write limits. The limits must lie within the device setpoint’s own write limits and fit its register: for a 16-bit register in tenths, −3276.8 to 3276.7. Without the cloud, the last setpoint stays in force. When the device setpoint cannot be read or written the program tries again on the next run.

API

Starters are in the templates.edgeProgram procedures of the API; every member can read them, and the assistant uses them too.

Procedure	What it does
templates.edgeProgram.list	Starters (id, name, description, summary), filtered by query
templates.edgeProgram.get	One starter with its placeholders in form order
templates.edgeProgram.instantiate	Builds the program for an MC252 endpointId from values; saves nothing

Placeholders work as in automation starters, with these kinds:

Kind	Value
fileName	A file name as typed (pumps becomes PUMPS.TXT); left out, the starter’s default, numbered when taken
parameter	A parameter id of a Modbus parameter of the endpoint
branch	A parameter branch id
phone	Digits with an optional leading +, or #1 to #4
number, duration, timeOfDay, weekdays, boolean, choice, text, list	As for automation starters; text with ascii takes printable ASCII only

instantiate returns { ok: true, fileName, description, source, parameters, diagnostics }, where diagnostics are the problems HMI finds when it checks the program with the device’s other enabled programs, or { ok: false, problems } as for automation starters, with these codes as well:

Code	Meaning
parameter_not_on_endpoint	Not a Modbus parameter of this MC252
parameter_encoding	Its encoding has no program type (formula, BCD, bit fields, bytes)
branch_not_found	Not a branch of the workspace
file_name_invalid, file_name_taken	Not an 8.3 .TXT name, or another program of the device has it

Save the program with edgeProgram.create (fileName, description, source), then each of parameters with parameter.create. An unknown starterId is edge_program_starter_not_found; an endpoint that is not an MC252 is edge_endpoint_unsupported.