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
Section titled “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-writewrite 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
Section titled “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
Section titled “Starters”Periodic logging
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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.
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.