How-to
How to run a Crimson 3.1 background task for raw serial data
Short answer
Put the parser in a Crimson 3.1 program whose Execution Task is set to Background 1, wrap it in a while(true){} loop with a blocking LF-terminated PortInput() read, and start it from the global On Startup action; a page OnTick parser only runs while its page is displayed and drops records at the captured worst case of 11 messages per second.
On this page
- Why does the parser need a background task at all?
- What does the serial stream actually look like?
- Where can Crimson 3.1 run a parser: OnTick, On Update, or Background 1?
- How do you build the background serial parser step by step?
- How do you handle a startup read that lands mid-record?
- Will the large signed fields fit an integer tag?
- How do you prove the parser keeps up at the worst-case rate?
- Questions asked
Run the parser in its own Crimson 3.1 program with a while(true){} loop, set that program's Execution Task from Same as Caller to Background 1, and start it from the global On Startup action; one blocking read per pass then keeps every record, on every page, at any rate the device is set to. The OnTick version that worked with fake data lives inside the three data pages, so it stops the moment you navigate away, and the burst rate captured in testing outruns a page that is not showing. The sections below give the framing rules for a stream with no start character, the build steps, the startup mid-record fix, the integer sizing for nine-digit signed fields, and the bench test that proves the worst-case rate.
Why does the parser need a background task at all? #
A page-side parser stops when the operator leaves the page, and at the captured worst case of 11 records per second that is up to 11 lost or merged records every second; a Background 1 program keeps reading whether or not any page is displayed.
The device transmits automatically and continuously, so records arrive whether or not a screen shows them. Crimson's best-practice guidance states that programs containing long loops should be set to run in a background task, and an endless read loop is the longest loop a runtime can hold. The current layout also carries three copies of the same parser, one in the OnTick action of each data page, all writing the same tags; the background program replaces all three with a single writer.
What does the serial stream actually look like? #
Each record is 28 characters including the terminating line feed — a sample reads -036298605,-000930576,15,63 followed by LF — split into 4 comma-separated fields, no start character, leading sign on the two large fields, so the line feed is the only frame boundary the stream gives you.
| Field | Sample value | Width |
|---|---|---|
| 1 | -036298605 | sign plus 9 digits |
| 2 | -000930576 | sign plus 9 digits |
| 3 | 15 | 2 digits |
| 4 | 63 | 2 digits |
A record can lead with a minus or a plus, so the conversion must accept both signs. Nothing but the commas and the terminating line feed marks structure, which forces one rule on every approach: read to the line feed first, split on commas second. The rate is user-settable — the device was seen at 3 to 4 records per second typically and at 11 per second in the worst capture, and it can be set down to 1 per second or slower — so every number below keys off the maximum setting, not the typical flow.
Wire time says the port is not the constraint. Worked example on assumed framing — read the real baud, data bits, parity and stop bits from the Crimson port settings and the device manual before reusing these numbers. At 9600 baud with 8 data bits, no parity and 1 stop bit, each character costs 10 bits, so one 28-character record occupies 28 x 10 / 9600 = 0.029 s, about 29 ms, on the wire. The captured worst case of 11 records per second gives a record period of 1 / 11 = 0.091 s, about 91 ms, so the port idles roughly 62 ms of every 91 ms — a duty cycle of 29 / 91, about 32 percent. The scheduling method, not the wire, is what drops records; at another baud rate, recompute 28 x bits per character / baud and compare it with 1 / records per second.
The panel only listens on this link, so land the device's transmit on the port's receive with a shared signal common — the same pin-matching discipline as building an RS-232 Modbus cable between an HMI and a controller.
Where can Crimson 3.1 run a parser: OnTick, On Update, or Background 1? #
Run it in a program with an infinite loop whose Execution Task is set to Background 1, because that gives one task, one blocking read and one record per pass, while OnTick dies with the page and the driver's On Update action fires at an unverified granularity.
| Where the parser lives | What triggers it | Catches every record? | Cost and risk |
|---|---|---|---|
| OnTick action on each data page | Fixed tick, only while that page is displayed | No — it passed at 1 record per second with fake data, but at 11 per second the tick must beat the record period and the page must be on screen | Same parser duplicated on three pages, three writers to one tag set |
| Program with while(true){}, Execution Task set to Background 1 | Started once from the global On Startup action, then loops forever | Yes, when the read blocks until LF and the parse finishes inside the record period | Occupies one background task; a pass without a blocking read spins |
| Raw serial driver On Update action | Driver event when data arrives on the port | Unverified — bench-test whether it fires per byte, per record or per buffer before trusting it | No dedicated task, but re-entry while a previous run is still active |
A driver-based exchange such as fixing an HMI Modbus device no response over RS-485 keeps framing, addressing and retries inside the driver; the raw serial driver instead hands you the characters as they arrive, so the parser owns framing, validation and timing. Decision: run the Background 1 program now, and treat On Update as a later optimization only after a bench test shows it firing once per complete record at the device's maximum set rate.
How do you build the background serial parser step by step? #
Create one program, set its Execution Task from Same as Caller to Background 1 on the Properties tab, wrap the body in while(true){}, make every pass reach a blocking read that ends on the LF character with a timeout, and start it from the global On Startup action.
- In the Crimson 3.1 development environment, create a new program and open its Properties tab.
- Change Execution Task from Same as Caller to Background 1, the setting that moves the loop out of whatever context would otherwise hold it.
- Wrap the body in while(true){} and make every pass reach a blocking or timed read; a pass that skips the read consumes the task spinning on an empty buffer.
- Receive with PortInput(), the raw-port read call in Crimson 3.1, and configure it to end on the LF terminator with a timeout so each call returns either a complete record or silence; check the argument list in the installed help for the exact parameters. The timeout here guards a silent wire — it is not the response window you tune when fixing an HMI PLC communication timeout over serial between an HMI and its controller.
- On a timeout or an empty return, skip the parse and loop again; never write the destination tags from a partial record.
- Split the line on the comma, require exactly 4 fields, convert each field, and write the results to the destination tags.
- Start the program from the global On Startup action so the loop runs for the life of the runtime.
- Delete the OnTick parsing code from all three data pages so exactly one writer updates the tags.
// illustrative pseudocode, not Crimson syntax
integer goodCount = 0; // records parsed and written
integer badCount = 0; // lines rejected on field count
string line; // one LF-terminated record
string fields[4]; // split result
while (true) {
line = ReadToLF(port, timeoutMs); // blocking: ends on LF or timeout
if (isEmpty(line)) { continue; } // silent wire: loop and wait
fields = split(line, comma);
if (fieldCount(fields) != 4) {
badCount = badCount + 1;
continue;
}
tag1 = toInt(fields[0]); // sign plus 9 digits, leading zeros
tag2 = toInt(fields[1]); // sign plus 9 digits, leading zeros
tag3 = toInt(fields[2]); // 2 digits
tag4 = toInt(fields[3]); // 2 digits
goodCount = goodCount + 1;
}
PortInput() is the call Crimson 3.1 provides for reading the raw port; ReadToLF, split, fieldCount, toInt, port, timeoutMs, line, fields and tag1 through tag4 in the snippet are illustrative names — match each to the function your installed version supplies and to its argument list in the help before running.
How do you handle a startup read that lands mid-record? #
Discard the first read after startup: the stream runs continuously with no start marker, so the program almost always joins mid-record and the first read returns a fragment — after that discard, reject any line that does not split into exactly 4 fields.
The field-count check rejects most fragments, but it cannot reject all of them: a fragment that happens to hold three commas splits into 4 fields and passes. That is why the first read after startup is discarded unconditionally instead of being trusted to the check. After one discarded read, every later read ends at a line feed, so the framing aligns itself and stays aligned for the life of the run.
Will the large signed fields fit an integer tag? #
Yes — nine digits plus a sign tops out at 999,999,999 and a 32-bit signed integer holds up to 2,147,483,647, so the widest field in this stream fits with more than 2 to 1 margin; size the destination tags as 32-bit integers.
The margin is 2,147,483,647 / 999,999,999 = 2.15, so the largest value this stream can produce sits at less than half the range of a 32-bit signed tag; the two-digit fields in the sample, 15 and 63, are trivially inside. One documented check comes before you trust the conversion: run a value with leading zeros, -000930576, and a plus-signed value through the conversion and confirm both come back as decimal — leading zeros must not be read as octal and a leading + must not be rejected. Crimson's conversion documentation states that behavior; the bench test below proves it on your hardware. Decision: 32-bit signed integer tags for the two large fields, no intermediate scaling before the write.
How do you prove the parser keeps up at the worst-case rate? #
Set the device to its fastest output rate — 11 records per second was the worst capture — run for several minutes, and goodCount must land within one record of elapsed time multiplied by the device rate, with badCount at 0 once the startup discard is behind it.
- Run at the fastest setting the device offers and stay there for several minutes.
- Compare goodCount with elapsed time multiplied by the device rate: at 11 per second, a 300-second run must produce about 3,300 records, within one.
- Confirm badCount stays at 0 after the startup discard.
- Compare the displayed tags against a captured raw string for the same record, once with a negative value and once with a plus-signed one.
- Change pages repeatedly during the run; the tags must keep updating with no data page displayed.
- Drop the device to its slowest setting and confirm the timeout path neither zeroes nor corrupts the tags.
Decision: design for the maximum settable rate, not the typical flow; the blocking-read loop holds any rate at which the parse finishes inside the record period, so if the device is later set above the captured worst case, rerun the elapsed-time x rate comparison at that setting before signing off.
Questions asked
What goes wrong if the background loop has no blocking or timed read?
The loop never waits, so it consumes the whole Background 1 task spinning between empty reads and the parser never sees a complete record. Give PortInput() an LF terminator and set the timeout comfortably longer than the longest gap between records the device can be configured to emit, so a slow but healthy stream is never mistaken for a dead wire.
Why must the program leave Same as Caller?
Left on Same as Caller, a while(true){} loop holds whichever context called it, a page action or the startup action, for as long as the loop runs, which is forever, so that context never completes its own work. Background 1 is the setting that detaches the loop from every caller; Crimson's guidance puts any program that contains a long loop there.
How many records per second could the port carry at 9600 baud, 8 data bits, no parity, 1 stop bit?
The physical ceiling is 9600 / (28 x 10) = 34.3 records per second, because each 28-character record costs 280 bits at that framing. Treat it as a ceiling only: the read, the field check and the tag writes must also finish inside each record period, so the design target stays the device's maximum set rate, which the captured stream capped at 11 per second.
When is the raw serial driver's On Update action the better choice?
When a bench test proves its granularity. Put a counter inside the action, stream the device at its maximum set rate, and check that the counter advances once per complete record with nothing dropped or duplicated. If it does, move the parse there and free the background task; if it fires per byte or per buffer, records get fragmented or the action re-enters, so stay on the Background 1 loop.
What should accompany a support case when the counts still disagree?
goodCount and badCount, the elapsed test window they cover, the port settings (baud, data bits, parity, stop bits), a raw capture of the stream at the failing rate, and the Crimson 3.1 database file. Escalate to the vendor's technical support when goodCount falls behind the device count despite a short parse, or when PortInput() returns truncated records the wire-time arithmetic says it should absorb.