Overview of PageGate Serial Interface Transcript for Video:
Welcome to the overview of the GetSerial interface. In this tutorial, we’ll be going over what GetSerial does and how it does it.
PageGate’s GetSerial interface monitors a serial/RS-232 line for incoming raw data strings. You can then configure the interface’s data parsing parameters to tell it what data in the stream is relevant. This interface can be used to monitor security and alarm systems, arduinos and raspberry Pi’s as well as anything else that can transmit information via serial.
It’s also important to note that you can monitor multiple serial ports simultaneously with the GetSerial interface’s companion SERIAL2ASCII modules. For information on how to configure SERIAL2ASCII, please see our SERIAL2ASCII video tutorial.
To configure the interface, run the PageGate Admin. Once there, go to Interfaces – GetSerial – Settings.
The ‘Serial Port’ field will need to match the serial port you want to monitor.
Baud Rate, Parity, Data Bits and Stop Bits should match the sending system’s requirements. For example, if your Arduino is transmitting at 9600 baud with no parity, 8 data bits, 1 stop bit and XonXoff handshaking, you would mirror those settings here.
Check Enabled, then click apply and say whether or not you want this enabled for all existing groups and recipients.
Next, go to the Program – Settings section.
In ‘Run on this Server’, check GetSerial, then click Apply. If you’re running PageGate as a Windows service, you’ll be prompted for credentials. Leave them blank and click Apply again.
Now that we’ve told the interface what to monitor and configured it to run, we’ll need to tell it how to break apart and understand the data it’s going to receive. To do that, expand Settings under GetSerial and let’s start with the Symbols section.
The Single Character Wildcard is a character that can be used in a search pattern to designate a location where any single character (or symbol) will be accepted as a match. For example if ? is the Single Character Wildcard, then the pattern ?use would be a match for words like fuse, muse, ruse, but would not match amuse or reuse.
The Multiple Character Wildcard is a character that can be used in a search pattern to designate a location where any group of characters (and symbols) will be accepted as a match. For example if * is the Multiple Character Wildcard, you could use the pattern *use to find muse, fuse, ruse, amuse, accuse or any other word or alphanumeric sequence that ends with the letters 'use'. When used by itself as a start pattern, the Multiple Character Wildcard would always match the first character of the input text.
The End of Record Symbol is a character that can be used in a search pattern to designate the last character of the input text, regardless of what that character is. The End of Record Symbol is most commonly used in End Pattern fields as a value that means "the last character of the input data". If this character appears within the body of a file scanned, the program will stop reading at the character and will not read in anything past it
The ASCII Value Delimiter is a character that means "the next three digits stand for an ASCII character value". This is normally used for expressing non-printable values like a carriage return, line feed, horizontal tab and other control characters.
As shown on under the interface, here are four bits of information that tell the GetSerial interface how to understand the data:
• Record
• Recipient
• Sender
• Message
The Record settings designate what part of data stream contains the message data (i.e. recipient, sender, message text).
For example, if * is your multiple character wildcard, then if you use a * as a start pattern and \013 as an end pattern. That would tell GetSerial to treat everything between the very first character received and the first carriage return is a record of information relevant to the message.
As another example, you could use the word START as the start pattern and the word END as the end pattern. That would tell GetSerial to treat everything between the words START and END as a record of information relevant to the message.
Basically, we’re telling PageGate that everything in between the declared characters is relevant data.
You’ll also notice that there is a Start Offset and an End Offset.
The Start Offset represents the number of characters before or after the Start Pattern to begin reading and these values can be expressed in positive or negative values.
For example, if you were using START as your start pattern, you could set a Start Offset of 5 to say that the text used as the start pattern should be skipped because it isn’t relevant for the Recipient, Sender or Message information. Using a value of -5 would say that 5 characters before the first character in the start pattern is the beginning of the record.
The End Offset, on the other hand, represents the number of characters before or after the End Pattern to not include in the record data. As with the Start Offset, these values can be expressed in positive or negative.
When finished, click Apply.
Now that we’ve declared what a record is, go to the recipient section.
The Recipient section determines where in the record data the recipient or group name will be found. However, if you want all messages triggered on the serial line to go to a specific recipient or group, you can select ‘Static Recipient’ and select that recipient or group from the dropdown.
If the data stream contains information about who the message should go to, you’ll need to tell PageGate where in the data stream that information appears by selecting the ‘Dynamic Recipient’ option and configuring the start and end patterns, as well as their corresponding offsets.
The Start and End Patterns tell PageGate that everything between the declared character or characters is the Recipient or Group name. For example, let’s say your data stream looks something like this:
START UNIT: 3 ALARM: CPU3 47C 00:03:12 11/07/2017 END
And that “UNIT: 3” represents who the message should go to.
Remember the Start Offset in the Record? We set that to 5, so when GetSerial scans for the recipient information, it’s searching this:
UNIT: 3 ALARM: CPU3 47C 00:03:12 11/07/2017
So, we would want to use an * as our Start Pattern, to tell the interface that the recipient information starts at the first character. Then, we would use ALARM as our End Pattern. This tells the interface that everything between the first character and ALARM is the recipient information.
However, the text ‘UNIT: 3’ doesn’t mean anything to PageGate, so we’ll have to translate that code in to the name of a recipient or group in the program. To do that, check ‘Use Lookup Table’ and click Edit Table.
Click Add.
We’ll want to use *UNIT: 3* as our Data In value. The asterisks indicate that any text, including spaces, could appear on either side of the phrase we’re interested in but we’re really just interested in this particular phrase.
For the data out, we’ll want to use the name of a recipient or group in PageGate. For example, if we wanted the UNIT: 3 messages to go to the it_alerts group, we would use their group name in the Data Out field.
When finished, click Apply then click Apply again.
Now we’ll need to configure the Sender section of the interface. The “Sender’s Name” is the text that will appear before the message to denote who or what sent the message and is used to construct the “Mail From” value when delivering SMTP/email messages. The Sender section determines where in the data the sender’s value can be found. This section uses the same pattern matching as the recipient section and can be configured similarly. Typically speaking, most systems won’t pass a sender’s name value in the data written and you’ll want to select Static Sender and enter a sender’s name.
The final section is Message. The Message section determines where in the record the message is found and uses similar Start and End Patterns. To use our earlier example, let’s say that our original data stream looks like this:
START UNIT: 3 ALARM: CPU3 47C 00:03:12 11/07/2017 END
And this is what it looks like after the record declaration:
UNIT: 3 ALARM: CPU3 47C 00:03:12 11/07/2017
And this is what it looks like after the recipient declaration:
ALARM: CPU3 47C 00:03:12 11/07/2017
The remaining portion of the data stream is available to be scanned for the message. If all of the information is relevant, you can use a * as a Start Pattern and a ~ as an End Pattern and that would configure the interface to treat everything from the first character to the last character as the message.
However, we could also use ALARM: as the Stat Pattern with a start offset of 6 but that makes the assumption that every message will be prefixed with the text ‘ALARM:’. If that text doesn’t appear but is specified as the start pattern, the interface will not recognize it as a valid message.
When finished, click Apply.
At this point, the GetSerial interface is now configured to monitor the serial port you’ve specified and will monitor incoming data streams for the patterns you’ve configured.
This concludes the video tutorial on the GetSerial interface.
|
