What’s a Communication Handle, and when would I want to use one?
OVERVIEW:
A Communication Handle will allow you to:
- Communicate with another device via SERIAL connection, like RS-232 or RS-485. This could be an Opto 22 product like our LED dimmer, or just about anything with a 232/485 port, like a GPS receiver. The physical connection can be either on your PAC-R, or PAC-S series controller, or via one of our serial SNAP-SCM- modules on the same rack as a PAC-R or PAC-EB series controller/brain.
- Communicate with another device via Ethernet (TCP or UDP). This device could be an inexpensive webcam, an LED sign, a wireless home thermostat, or even an IP to IR converter (so you can control devices with infrared remotes, like your TV or my favorite remote-controlled LED candles).
- Read/write/create/update a FILE either local to where your strategy is running (including the microSD card on your PAC-R or -S series controller), or on an FTP server your PAC/SoftPAC can access.
Note on EMAIL and WEBSITES:
In older versions of our products, you might’ve used a Communication Handle to either send an email or access a website over the Internet (because those are just packets sent via Ethernet using tcp/ip; in particular, SMTP for email and HTTP for website access). However, modern versions of PAC Control and our control engine firmware now include commands like SendEmail, HttpGet and HttpPost which make these tasks much easier.
Note on SERIAL Communications:
Because our serial modules, like the SNAP-SCM-232 or SNAP-SCM-485-422, are IP-addressable (use the IP address of the PAC-R or PAC-EB, and the port configured with PAC Manager), you’ll use a comm handle that starts with “tcp:” and includes that IP/port for the particular module/port.
This means you could have your strategy running on one PC or PAC communicating to a remote PAC-R or PAC-EB which is essentially acting as an Ethernet to Serial converter. Neat-o!
When using the (faster) on-board serial connections available on PAC-R and PAC-S series controllers, your comm handle value will start with “ser:” followed by baud settings. If you’re using a PAC-R, you’ll need to change the on-board Port 0 to be configured for “none” rather than the default of PPP or your Open command will fail with a -20 (more details on this an other common errors below).
Documents & General Guidelines:
1700: PAC Control User’s Guide, especially Chapter 10: Programming with Commands, the Communication Commands section, which explains how: “Typically, a communication handle is used to open communication, to transmit and receive data, and to close communication.”
1701: PAC Control Command Reference, especially the Communication Commands
1642: File Management & FTP Tutorial (even if you’re not using FTP, check out the file section)
As you’ll see in the examples below and in the manual, in some cases you’ll want to leave a comm handle open (for example, with TCP or UDP) as long as possible. In other cases, you might open, close, and re-open often (for example, with a file where first you’ll open to write, then close and re-open to read/search).
The manuals and examples include information on error check and reporting. These commands have lots of ways they could fail (the file you want to open doesn’t exist yet, the device you’re trying to communicate to isn’t turned on or doesn’t have the IP Address or baud rate you thought), so error checking is especially important.
Most of the Communication Commands return a status value. Your logic should check for the errors you expect to see during normal operation scenarios (for example, a “timeout” or “can’t connect” if the network is down or remote TCP device is powered off). Check the on-line help / command reference for Status Codes.
Also, in PAC Control under Help > Error Lookup… you’ll find a handy error code look-up:
DEBUGGING TECHNIQUES
In PAC Control’s debugger
Let’s say you’ve successfully opened your communication handle, and you’re trying to troubleshoot the rest of your logic. Besides looking at the error codes returned by the commands you’re using, there are a couple of other ways you can “see” what’s happening with your communication handle.
In PAC Control Debug, if you double-click on the comm handle you’ll just see its value, but if you click on the Maximize button…
You’ll see the current state (typically: “Open” or “Closed”), and the Number of characters waiting (to be “received”):
In this example, I’m showing a tcp comm handle.
Notice that here I see there are 7 characters waiting, even though I sent only 5 (“hello”) via PuTTY:
Why might that be? You could use a tool like Wireshark to sniff and examine the actual packets (I won’t get into details of PuTTY or Wireshark here, but those tools are very commonly used and you’ll find loads of info, including videos, all over the Internet).
Here’s a clue and the next couple of commands you’ll often want to use after you’ve opened your comm handle:
When you receive the string and look at it in the debugger, you might be wondering what that little dot is at the end of your string, since the string you sent was just a “hello” with no period.
Again you’ll want to expand the debug window:
Notice some things about what I’m seeing in that maximized window:
- The “current width” is 6
- The ASCII code for that 6th/last character is 13
- The “value” of my string is grayed out, so I couldn't delete that last mystery character if I wanted to
- If I click the “ASCII” button, I can change the view to “HEX” as shown here, and now I can edit it:
Why? Let’s take these in order:
The current width is 6 even though I did a “Receive String” and my comm handle now shows 0 waiting. What happened to that 7th character? The “Receive String” command ate it.
What? Because the “Receive String” command uses the EOM or End Of Message character, in this case we set ours to be 10 or LF “line feed” if we look at our favorite ASCII Table like the one on www.AsciiTable.com or found in form 1700, the PAC Control User’s Guide:
Or if you go way back you might have one of these:
In any case, the program PuTTY sends a CR LF (Carriage Return / Line Feed) or Hex: 0D 0A pair when you press enter in the terminal window. Since the comm handle lets you have just one end of message character, we set that to 10 (or hex 0A) since that’s the end of the message.
Depending on what I need to do with this message, I might also need to get rid of that 0D or 13 later, which I can do manually by switching to Hex and deleting it in the debugger.
Note that if you have any non-printable characters, like those in the range 0-31, the debugger will assume you have data here (vs. a regular string) and will require you switch to Hex since there is no key on your keyboard for entering a CR or LF, for example.
If the data you’re receiving or sending is NOT a string like “hello” but rather data like a numeric table, and you’re seeing very different values than what you expected, it could be that your byte order (or “Endianess”) is mismatched. The command: “Receive Numeric Table Ex” has an option to change this for you automatically, as your values are received.
COMMON ERRORS
Besides the byte-order problem just mentioned, other errors resulting from communication handle use, like many other commands in PAC Control, could show up either in the Message Queue or as a status code returned by the command.
Here are some of the most common errors people see when using communication handles:
-20 = This typically happens when you’re using the on-board 232 port on a SNAP-PAC-R and you’ve not changed the default settings for that port (it defaults to PPP). A couple of ways to solve this:
-
Use PAC Manager
a) Go to: Tools > Inspect, click Communications > Communications Port Control and change that first drop down to “None.” Note it’s at address F031 0400 in the memory map. Click: Apply.
b) Click: Status Write, then under Operation choose “Store configuration to flash” and click “Send Command” -
In your strategy, write the value of 0 to that address of: 0xF0310400 for example using the I/O Unit - Memory Map command: WriteNumToIoUnitMemMap command
-36 = “Invalid command or feature not implemented. A firmware upgrade may be required to use this feature on this type of communication handle.” If you have the latest-and-greatest firmware, then your PAC may not support what you’re trying to do, for example, SoftPAC does not support use of the “ser:” command (most modern PCs don’t have an on-board serial port). To communicate with a serial device via SoftPAC or PAC Sim, consider using a serial module on a rack with a SNAP-PAC-R or SNAP-PAC-EB. Many of our customers have also used third-party Ethernet to 232 conversion devices.
-39 = “Receive timeout.” If you’ve inspected your comm handed in the debugger (as described above) or have used the “Get Number of Characters Waiting” command to determine there are characters to received, then double-check the number of characters requested or if the command your using expects an EOM character. Consider using the “Receive N Characters” command. Also keep in mind that the “Receive Numeric…” commands will receive multiple bytes per table element. You’ll have 4 bytes/characters (32 bits) for each element in an Integer 32 Table and 8 bytes/characters (64 bits) in each element in an Integer 64 Table.
-203 = “Driver could not be found or loaded. Make sure the communication handle designator (udp, tcp, ftp, file, etc.) is in lowercase letters and correctly spelled.”
Other tools:
Firefox
If you’ve just opened a file comm handle, that “number of characters waiting” would represent the size of your file. The Firefox browser (for easy download, visit: www.getfirefox.com) is also a handy tool for checking out what files currently exist on your SNAP-PAC brain or controller. Just type “ftp://” and the IP address of your PAC in the address line:
In the image here, notice that first file has no size (it’s empty) so you’d receive a timeout error if you tried to do a “receive” on a comm handle using that file. Note that from within Firefox you can click on the file and look at it (handy for troubleshooting when your logic is adding data to that file).
Notepad++
I mentioned CR LF characters above in that TCP example, but you’ll also commonly see those together at the end of lines in a file. Notepad++ makes it easier to see those often-invisible characters by selecting View > Show Symbol > Show End of Line:
Hoping that helps as you use Comm Handles. Below find a few more examples with code you can “leverage” to save you some time…
-OptoMary
FURTHER READING / EXAMPLES:
Serial examples:
GPS: Parse GPS data from your PACs 232 port
Optomux/LED dimmer: Simple Optomux protocol sample chart
TCP/FILE: [Scrape/parse a website]Another HTTP Web page scrape: of a Campbell Scientific CR1000 Datalogger
File examples:
Don’t forget that PAC Display has all kinds of built-in logging (which happens on that Windows PC).
Data logging example (also shows how to use FTP and handle errors)
Log when certain values change in your strategy
Getting data into a google doc spreadsheet via IFTTT
Re-formatting trend data for your spreadsheet