Mapping PLC signals: states, scrap, triggers and writes

Updated Oct 8, 2026

Shop Floor

Mapping PLC signals: states, scrap, triggers and writes

Tell Shop Floor what your machines' raw values mean, run scripts on thresholds, describe your equipment, and control exactly which tags may be written.

Permissions: Every page here needs the DataMagik - Builder role, the Shop Floor license feature and the Shop Floor OT connectivity license feature. Giving a tag a write class, or switching a Plex write-back opt-in ON, also needs the OT write license feature. Making a tag read-only or switching an opt-in OFF never does.

These screens work per site and build on tags bound on the Tag map (/shop-floor/settings/tag-map); see Connecting PLCs.

State map: what each machine value means

A machine reports a number or a word; Plex needs one of your own statuses. The State map page (/shop-floor/settings/state-map) is where you say what each value means. A value is never guessed: until it is mapped, its events record with no status and are missing from availability.

Pick the Site. If you see Plex statuses have not been synced for this site, run the site's Plex sync first; a value can only be mapped to a status Shop Floor knows.
Work the Values nobody has explained panel at the top. It lists values machines sent that match no rule, noisiest first. Click Map this to load one into the form.
In Add a mapping, fill in Raw value (for example 3), choose what it Means status, and choose Applies to. Leave it on Every workcenter at this site unless one machine uses a different convention. Optionally add a note, then click Save mapping.

The Mappings list shows plant-wide rules first, with per-workcenter overrides beneath them marked (override — wins here). If you remove a mapping, the values it covered record with no status until another rule matches them.

Scrap reasons: what a reject counter counts

The Scrap reasons page (/shop-floor/settings/scrap-reason-map) says which Plex scrap reason each machine's reject counter counts. An unmapped counter books no scrap at all.

Click Sync reasons from Plex if the page says Plex scrap reasons have not been synced for this site.
Check Reject counters nobody has explained. Mapping now does not recover parts already lost.
In Add a mapping, choose Applies to (default Every reject counter at this site), pick the Counts scrap reason, optionally add a note, and click Save mapping.

As on the state map, a per-workcenter rule overrides the plant-wide one.

Triggers: run a script when a signal enters a band

The Triggers page (/shop-floor/settings/triggers) runs a script when a machine signal moves into a band. You can only watch analog tags, such as rate, temperature, pressure or speed. Triggers are evaluated at the plant's connector, and a crossing reaches the cloud within about 15 seconds, not instantly.

Under Add a trigger, give it a Name that is unique on the site, such as Press over temperature.
Choose the tag to Watch and the script to Run script. The script runs in the cloud, not on the machine.
Set the band with At or above, And at or below, or both. Leave a field blank for no limit on that side. Zero is a real threshold.
Set the Re-arm margin. It is required, in the tag's own units: how far the value must travel back out of the band before the trigger can fire again, so set it wider than the signal's normal wobble.
Leave Armed ticked and click Save trigger.

Caution: If the machine is already inside the band when you save, the script runs once straight away. A triggered script also has the same powers as any other script, so if it writes to Plex directly, it really writes. To have a status write follow your approval settings, submit it through the write outbox instead.

The script's input includes the value that crossed in, crossed_at, and tags (the machine's other mapped tags, keyed by role). Unticking Armed stops evaluation within seconds.

Equipment and models

The Equipment and models page (/shop-floor/settings/equipment) covers equipment that is not a Plex workcenter, such as AGVs, AS/RS, chargers and conveyors. You add equipment and bind its signals on the Tag map; this page gives it a model.

Models: click Add a model and enter a Model code (for example TUG-1200), what it Carries, Payload (kg), Width class, battery, speed and charging interfaces.
Equipment at your site: give each piece of equipment its model. An AGV without a model cannot be matched to a transport order.

An AS/RS can be given a job interface (Set job interface), and an AGV can be bound as a VDA 5050 vehicle. Both write to the equipment, so the gates in the next section apply. See Fleet.

OT writes: write classes and the connector allowlist

Every bound tag is read-only until you give it a Write class on the Tag map:

None — read-only: the default. Reading is unaffected.
Indicator — lights and horns.
Setpoint — only inside the range the site's connector allows.
Command — only while somebody is identified at the machine.

With a class, a script calling plc.write can set the tag. Every attempt, including refused ones, is recorded and appears in that row's History. Re-binding a tag without a class makes it read-only again.

The connector at the site has its own gate, which is a file named ot_write_allowlist.json next to the connector executable. It is edited only at the site, never by the cloud.

With no allowlist file, the connector writes what the platform's own gates allow.
Once the file exists, only nodes it lists are written, and only with the same class. A setpoint must also fall inside the listed minimum and maximum. If the file is empty or cannot be read, every write is refused.
Add a node with -ot-allow, together with -ot-endpoint and -ot-class. A setpoint also needs -ot-min and -ot-max. Remove a node with -ot-deny, and show the list with -ot-list.
-ot-writes off turns all writes off on that connector, overriding everything the platform allows. -ot-writes on turns them back on.

The connector reads the allowlist fresh on every write, so a change takes effect immediately. The Tag map's warning updates after the connector service restarts.

For sites that will not accept an agent that can write, there is a read-only build of the connector. It contains no write path, refuses every write, and the Tag map says it "was built without tag writes". It does not self-update; replace it with the next read-only build.

Plex write-back, per machine

The Plex write-back, per machine panel on the Tag map controls what each bound machine's own PLC may write into the site's Plex. Every switch is OFF until you turn it on:

Status writeback turns the machine's state into Plex status log rows. It needs a state binding.
Production booking books its counter as parts. It needs a part_count binding.
Scrap booking takes its rejects off a container. It needs a reject_count binding.

Click Turn on and confirm with Yes, turn on. Turn off takes effect immediately, with no confirmation.

Mapping PLC signals: states, scrap, triggers and writes