MC252 edge programs

An edge program is a taskfile that runs on an MC252 controller. Programs are part of the workspace setup, like endpoints and parameters: you create, edit, review, and synchronize them in the workspace, and the workspace deploys them to the device. See the MC252 program language for the programming language and Write programs for an MC252 for the checks HMI runs on the source.

Programs

Each program belongs to one MC252 endpoint: a PIN-connected endpoint whose SKU is mc252. Other endpoints cannot have programs. A program has:

Field	Meaning
endpointId	The MC252 endpoint that runs the program
fileName	The file name on the device: 8.3, upper case, extension .TXT
description	Optional text
enabled	A disabled program stays in the workspace and is never deployed (default true)

The source is the workspace file edge/<endpointId>/<fileName>: UTF-8 text without NUL characters, at most 256 KiB.

File names have one to eight characters from A–Z, 0–9, _ and -, then .TXT, and are unique per device. Windows device names such as CON.TXT are refused. Setup pages and the assistant upper-case a typed name and add .TXT when it has none. A name used with GETUPDNAMEIDX needs a digit.

Deleting a program deletes its source file, and the next deploy removes it from the device. An endpoint that still has programs cannot be deleted (endpoint_in_use): delete its programs first. Deleting the endpoint itself never changes the device, so programs that no deploy has removed yet stay on it and keep running. The deploy status Nothing deployed (never) means that no programs from HMI are left on the device. See Remove programs from a device.

Disconnecting an MC252 from the other workspaces that hold it also deletes their programs for that device.

Load order and validation

Programs that HMI deploys load in file name order (byte order of the upper-case names): the device loads them in the order of their slots in the folder, and the deploy places them in name order. Load order decides which program gets shared memory first. Only one program may write a mapped parameter: when a later program writes it too, the device rejects that whole program as a compile error. File names therefore set the order: 10PUMP.TXT loads before 20ALARM.TXT.

HMI validates each device’s enabled, non-empty programs together, in load order. Programs with validation errors can be saved, pulled, and pushed; errors only block deploying. While any enabled program of a device has an error, nothing is deployed to it and the device keeps running its last deployed set. Empty programs are never deployed.

Deploying

A deploy uploads the programs, makes the device load them, and checks that it runs them. Steps are in Deploy programs to an MC252.

When a deploy runs

• With Deploy on save (autoSync) on, the default, saving a change to a device’s enabled programs or to device-side logging starts a deploy, whether the save comes from Setup, the assistant, the API, or hmi push.
• With Deploy on save off, changes wait for Sync now (edgeProgram.syncNow). A sync also works with Deploy on save on, for example to put back programs someone changed on the device.
• When the device is offline, the status is Device offline, and the deploy runs again when the device comes back online.
• A failed upload is retried for a few minutes before the deploy counts as failed. After a failed deploy, HMI tries again at its next check of the device when Deploy on save is on; with it off, the next sync tries again.
• While any enabled program of the device has a validation error, nothing is uploaded and the device keeps running the programs it has.
• A device connected in more than one workspace gets no deploys; see devices in several workspaces.

HMI also checks the device’s files regularly and whenever the device reloads its programs. With Deploy on save on, a change made on the device is replaced by the workspace’s programs; with it off, the status shows Changed on the device.

What a deploy does

A deploy:

• sets the device to log task data in the .DAT format that HMI imports and, with device-side logging on, turns on the device log that SYSLOG output needs. The device applies these settings when it restarts;
• removes every other file from the device’s /TASKS/ folder: programs placed there by hand, and programs removed or renamed in the workspace. Before it removes or overwrites a program that HMI did not put on the device, it keeps a copy in the workspace as edge-removed/<endpointId>/<time>/<FILE NAME>. Files larger than 256 KiB are removed without a copy. Values that the remaining programs keep with MEMFILE survive;
• uploads the programs that changed, makes the device reload them, and checks that it runs them. If an upload fails, the device keeps running its programs as before.

A deploy that loads programs restarts every program on the device, whatever changed. Values in memory that is not persisted are lost. A deploy that changes no program file restarts nothing, for example when only device-side logging changed.

Deploy status

The endpoint’s Programs tab shows the deploy status live (edgeProgram.deployStatus, edgeProgram.watchDeployStatus in the API). To wait for a deploy in one call, pass waitMs (up to 30000) to edgeProgram.deployStatus: while a deploy is queued or running, it returns once the deploy ends or the time passes, whichever comes first. Waiting never stops the deploy.

State	API value	Meaning
Nothing deployed	never	No programs from HMI are on the device and nothing waits
Changes waiting	pending	Changes wait for Sync now or the next deploy
Deploying	deploying	A deploy is queued or running
In sync	synced	The device runs the workspace’s programs
Deploy failed	failed	The last deploy failed: a device compile error names the program and line; otherwise the tab says why the deploy failed
Blocked by errors	blocked	A program has validation errors, so nothing was uploaded
Device offline	offline	The device could not be reached; the deploy runs when it is back
Connected in another workspace	conflict	The device is connected in more than one workspace
Changed on the device	drift	Files on the device changed outside HMI while Deploy on save is off

The status also lists the programs and tasks the device runs and when it last loaded them. A failed deploy notifies the workspace’s owners, admins, and editors.

Live state

edgeProgram.watchLiveState reads a program’s state from its device about every intervalMs (at least 1000) while subscribed, and stops when the subscription ends; edgeProgram.readLiveState reads it once. Both need the editor role, and fail with endpoint_disabled while the endpoint is disabled. Each read is live, not_running (the device does not run the program), or unavailable with a reason: offline, device_refused (for example while the device loads programs), or own_unit_off (the device’s own Modbus server is off). A live read has:

Field	Meaning
taskIndex	The program’s task on the device, in load order from 0
stats	Minimum, average and maximum period between runs and duration of a run, in ms, since the last load
variables	Each variable or array by name and first index, its values as decimal strings, null while unknown
conditions	Each condition or array of conditions, its values true, false, or null while unknown
namesCurrent	False until HMI has read the names of the device’s current load; items then have no name
unreadable	How many variables and conditions the device does not report: past its fifth task, 250 variables, or 1000 conditions

HMI reads the names from the program’s .MAP file on the device after each deploy and each reload it sees, and uses them only for that load. The state itself is read through the device’s web API, which may read these registers without the device’s admin password; a read waits up to a few seconds while a deploy holds the device and then reports device_refused.

Devices in several workspaces

An MC252 can be connected in more than one workspace. While it is, no workspace deploys programs to it, and every workspace that holds it shows Connected in another workspace. The device keeps running the programs it has. Owners, admins, and editors of workspaces with programs for the device are notified.

Edge settings

Each MC252 endpoint has edge settings, under Settings on its Programs tab (settings.edge of the endpoint in the API):

Setting	Default	Meaning
Deploy on save (autoSync)	on	Deploy program changes as soon as they are saved; otherwise wait for Sync now
Device-side logging (deviceLogging)	off	The device log that SYSLOG output and run-time errors need
Readings import period, minutes (readingsPullMinutes)	15	How often readings that programs log on the device are imported (1–1440)

Edge settings exist only on MC252 endpoints.

Device log

edgeProgram.readDeviceLog reads the MC252’s system log, /LOGS/SYS.LOG on its memory card, from the device. It needs the editor, admin, or owner role, since the log also holds the device’s own system events. HMI keeps no copy; the caller keeps the cursor.

Input	Reads
neither	the latest entries, up to 32 KB of the log
after	what was logged since the cursor of an earlier read; only new bytes are read
before	the entries before start of an earlier read

entries come oldest first. Each has the byte offset in the log, the device time at (UTC; null while the device clock was not set), the text, and a kind:

Kind	Entry
message	a line a program wrote with SYSLOG, or a firmware line without a known prefix
error	an error no handler caught: error has the firmware number, code, and line
system	a firmware message
restart	the device started

The device does not log which program an error came from. For an error logged since the device last loaded its programs, error.programs is the only program loaded, or else the loaded programs whose task last failed with the same code. It is empty for an earlier error, which may come from programs the device no longer runs, and when no program matches.

reset is true when the entries do not continue the after read: the log was cleared, replaced, or grew by more than 32 KB since. They are then the latest entries and replace the earlier ones. size is null when the device has no log yet. A line the device is still writing is left for the next read.

The device logs program messages and unhandled errors only with deviceLogging on and applied (see Edge settings). It writes its log in batches, 5–15 seconds after a message.

Recorded readings

Readings that programs record with PARAMLOG in the binary .DAT format are imported into history once per readings import period and right after the device comes back online. A device held by several workspaces is imported once, at the shortest period any of them sets, for all of them. Readings reach history within one import period; the last few seconds a device recorded can wait for the next import. HMI deletes each file from the card after its readings are stored and stores no reading twice. Disabled endpoints and suspended workspaces get no recorded readings.

Before each import, HMI compares the device clock with the server’s. While they differ by more than five minutes, nothing is imported or deleted, the endpoint’s status page shows a warning with the offset, and the owners, admins, and editors of each workspace holding the device get one notification; it is withdrawn once the clock is right. The next import then brings in everything the device recorded meanwhile, with the times the device gave it, so readings recorded while the clock was wrong can be shifted in history.

Setup marks a parameter that receives recorded readings with a history icon next to its name; hovering it, or tapping it on a phone, shows the import period, the last import, and the time through which the history is complete. Such parameters keep history without a background reading period. Dashboards count them as recorded; a counter total for a period that ends after the complete-through time shows Until … until the next import brings in the rest.

A record binds to every Modbus parameter of the endpoint whose unit ID, table, and first address match. The record’s registers fill the parameter’s addresses in their order, from the first address on; a parameter needing a register the record does not hold gets no reading. A bit record matches a coil or discrete input, a register record a holding or input register, by the read-only flag of its type. Records of the device’s own registers (MBSELF) use the device’s own Modbus unit ID, 111 unless it was changed on the device. The value is decoded from the recorded register bytes with the parameter’s value type and stored at the recorded time.

Records of other sources (LoRaSens) are not imported.

Addresses without a parameter

Records without a matching parameter are kept for 90 days after their recorded time. The endpoint’s Recorded readings tab lists their addresses, the 500 most recently recorded first, with the number of stored records, the last recorded time, and the last value as the device converted it (an F32EPnR / F64EPnR value is the float multiplied by 10ⁿ and rounded).

Create parameter on that tab creates a Modbus parameter for the address and then copies the stored records into its history, skipping readings it already has. A parameter created any other way (the API, hmi push, a template) gets the readings recorded after it exists; its stored records are copied in with deviceLog.backfill (readings API calls). Steps are in Bring recorded addresses into parameters.

Value type for a logged parameter

The record keeps the registers the device read, in Modbus order, and the parameter’s value type decodes them as it would a live read. The table lists the value type that reads the registers the way each device type does. The device’s scaling (EPnR) applies only to its own converted value, not to the registers. The parameter’s addresses cover the registers of the type: one per two bytes, starting at the logged address.

Type codes	Device type	Value type
6	BIT	bool on a coil or discrete input
0 / 20	UINT16 / UINT16BLE	int, byteLength: 2, unsigned-int (20: swap: "bytes")
1 / 2	INT16 / INT16BLE	int, byteLength: 2, signed-int (2: swap: "bytes")
21 / 22	UINT8 / INT8	one register; int of its low byte (leave-last-byte-in-word)
23 / 24 / 25	UINT32 / BLE / WLE	int, byteLength: 4, unsigned-int
3, 7 / 4 / 5	INT32 / BLE / WLE	int, byteLength: 4, signed-int
26 / 27 / 28	INT64 / BLE / WLE	int or bigint, byteLength: 8, signed-int
8, 11, 14, 17 / 9, 12, 15, 18 / 10, 13, 16, 19	F32EPnR / BLE / WLE	num, byteLength: 4, float32
29, 32, …, 47 / 30, 33, …, 48 / 31, 34, …, 49	F64EPnR / BLE / WLE	num, byteLength: 8, float64

BLE (byte-little-endian) types need swap: "bytes", WLE (word-little-endian) types swap: "words". See value types for the fields and the MC252 program language for the type list.

Synchronization

hmi pull writes programs to the checkout and their sources to edge/<endpointId>/<fileName>. hmi push sends both. A program and its source are separate for conflicts: a changed description and a changed source conflict and resolve independently (hmi resolve edge_program <id>, hmi resolve file edge/<endpointId>/<fileName>).

hmi check, and push before it sends, reject:

• a program or edge settings on an endpoint that is not an MC252;
• two programs of one device with the same file name, or an invalid file name;
• a program without its source file, or a file under edge/ that is not a program’s source;
• a source that is not UTF-8 text, contains a NUL character, or is larger than 256 KiB.

Validation errors and warnings in the sources are printed as warnings and do not stop a push.

A program’s file name is also the name of its source file. Rename a program in the web app, then pull; see Rename, disable, or delete a program.