Overview of PageGate Serial2ASCII Interface Transcript for Video:
Welcome to the video tutorial on how to configure PageGate’s SERIAL2ASCII module. In this tutorial, we’ll be going over how to configure the SERIAL2ASCII module to monitor a COM port or serial/RS-232 port.
SERIAL2ASCII is a companion module for GetSerial interface and unlocks the ability to monitor additional serial/RS232 ports or modems, up to as many as you need. Messages received by this module are output to a directory as a text file that is then read in by the GetASCII API. This module requires the GetASCII API to function.
The first step is to create a directory for the SERIAL to ASCII receiver.
This can be any folder accessible to PageGate, whether on the local hard drive or by UNC path to a network resource. However, if PageGate will need to reference a network resource, the services relevant to these processes will need permission to access it. For more specific information on this, please see the ‘Run Styles’ section of PageGate’s documentation.
I recommend creating a sub-directory of the PageGateData folder called SERIAL2ASCIIX where X is the number of the interface. By default, c:\PageGateData\SERIAL2ASCII1\
After you purchase the SERIAL2ASCII module, you’ll be sent a zip file containing the relevant files for the module and you’ll want to unzip the SERIAL to ASCII zip file in to the folder you just created. By default, c:\PageGateData\SERIAL2ASCII1\
Next, open SERIAL2ASCII.ini in your preferred text editor, like Notepad or Wordpad.
To give you a little more information, this .ini file controls the behavior of the SERIAL to ASCII receiver.
Change RunStyle=Application to RunStyle=Service
Change SwitchStyle=False to SwitchStyle=True
Set DataFolder= to the directory you created for SERIAL2ASCII. By default, DataFolder=C:\PageGateData\SERIAL2ASCII1\
Set ComPort= to the COM or serial port that should be monitored.
Set ComSettings= to the communication parameters required. Values must be passed as baud rate,parity,databits,stopbits
For example, this string would use 9600 baud, no parity, 8 data bits and 1 stop bit:
ComSettings=9600,n,8,1
and this string would use 1200 baud, even parity, 7 data bits and 1 stop bit:
ComSettings=1200,e,7,1
The Symbols section declares that certain characters should have special functions.
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.
The Record section designates what part of data stream contains the message data (i.e. recipient, sender, message text).
For example, assuming * is your multiple character wildcard, if you use a * as a start pattern and \013 as an end pattern. That would tell the module to treat everything between the very first character and the first carriage return received 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 the module to treat everything between the words START and END as a record of information relevant to the message.
Basically, we’re telling the module 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.
Now that we’ve declared what a record is, we’ll need to configure the recipient parsing.
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 enter the name of a recipient or group in Static=
Static= has a value, the start and end patterns are not referenced and all messages will be delivered to the static recipient or group specified.
If the data stream contains information about whom the message should go to, you’ll need to tell the module where in the data stream that information appears by configuring the start and end patterns, as well as their corresponding offsets.
The Start and End Patterns tell the module 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.
Now we’ll need to configure the Sender section.
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 write a static value in the Static= field.
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, save and close the ini file.
Next, open pininfo.txt in your preferred text editor, like Notepad or Wordpad.
This file tells SERIAL2ASCII what range of numbers can be accepted as valid IDs. The format of the entries defined in this text file is:
"Starting PIN", "Ending PIN", "recipient type"
If you would like ID numbers in a range to be recognized as the recipient's name (not using ad-hoc, but using numeric recipient names in PageGate), use the text "PG_Recipient". For example, this would configure the SERIAL2ASCII module to accept any 4 digit numerical ID as a recipient name:
"0001","9999", "PG_Recipient"
If you would like ID numbers in a range to be passed through the module as intact ID's to another source in an ad-hoc range, use the name of a Recipient in PageGate whose type is Ad-Hoc. For example, this would configure the SERIAL2ASCII module to accept any 7 digit ID as a freeform value to pass to the ad-hoc recipient named adhoc1:
"0000001","9999999","adhoc1"
After declaring the appropriate ID ranges, save and close the file.
Now that we’ve configured the SERIAL2ASCII module to receive messages, we’ll need to create and start its Windows Service. To do that, run a command prompt with elevated permission. To do so, go to your start menu and search for the word ‘command’. When ‘Command Prompt’ comes up, right click on it and select ‘Run as Administrator’.
Next, change directory to the SERIAL to ASCII receiver's program directory. By default, c:\PageGateData\SERIAL2ASCII1\
Type the following and hit enter:
SERIAL2ASCII1 /install
Now open the Services list in Windows and find the SERIAL 2 ASCII 1 service. Then right click on it and select ‘Start’.
The final step is to configure the GetASCII API to process the SERIAL to ASCII module’s messages.
In the PageGate Admin, go to Interfaces – GetASCII – Settings. If you already have a polling directory specified, you can skip this step. If you do not have a polling directory, we would recommend creating c:\PageGateData\ASCII\ and specifying that.
Next, go to Interfaces - GetASCII - Settings - Advanced Polling - Files.
Click Add.
Specify the following:
Recipient: *
From: Leave blank or specify a value
File(s): *.s2a
Path: Specify the output path of the SERIAL to ASCII receiver. By default, c:\PageGateData\SERIAL2ASCII1\
File Type: Standard
Click Apply, and then click Apply again.
At this point, the SERIAL2ASCII receiver is monitoring for your serial or modem messages and the GetASCII interface is configured to process the messages once they’re received.
This concludes the video tutorial on how to configure PageGate’s SERIAL2ASCII module.
|
