As you may know, you can record what happens on a serial line with the Yocto-RS232. It's very useful when you want to perform reverse engineering on an unknown communication protocol. Until now, the method that allowed us to do this was a bit rough. This week, we present a new, more user-friendly, API function as well as a small application that uses it.
How to snoop with a Yocto-RS232
You can indeed configure the Yocto-RS232 so that it spies listens to what happens on a RS232 line. To do so, you simply need to insert a small adapter on the connection, connect a Yocto-RS232 to this adapter, and that's it. The said adapter is sold ready-made by Yoctopuce under the name RS232-Snooping-Adapter, but you can build your own: it doesn't contain any electronic component and you can find the wiring diagram in the Yocto-RS232 documentation.
The Yocto-RS232 can listen on a serial line thanks to a small adapter
When everything is connected, you only need to configure the Yocto-RS232 in snooping mode. In this mode the Yocto-RS232 can listen to transmition whatever their direction is. Until now, to see what the module had recorded, you had to call a special URL of the VirtualHub and you obtained the raw data in text mode. It wasn't necessarily the easiest to use.
The snoopMessages function
If you update your API and your Yocto-RS232 firmware, you then have access to the new YserialPort.snoopMessages() function which returns the list of the recorded messages as an array of YSnoopingRecord objects containing:
- The message direction (RX=0 , TX=1)
- The elapsed time, in ms, since the beginning of the preceding message
- The message content
With three lines in Python, here is an example showing you how easy it is to use:
messagesList = serialPort.snoopMessages(0)
for msg in messagesList:
print (str(msg.get_time())+"ms " + str(msg.get_direction()) + " " + msg.get_message())
A few comments
- The snoopMessages() function returns the content of the Yocto-RS232 buffer since the last time it was called. You must therefore call it regularly to obtain the messages in real time.
- If the serial port is configured with an ASCII protocol, YSnoopingRecord.get_message() returns the message content in clear. If it's a binary protocol, it returns the message as an hexadecimal string.
- The Yocto-RS232 buffer is circular, you must therefore call the snoopMessages() function regularly enough to ensure not losing messages.
- The maximal time between two messages, returned by YSnoopingRecord.get_time(), that the Yocto-RS232 can compute is 60 seconds. So, if you obtain a value of 60000ms, you know that potentially more than a minute happened since the latest message.
- The time returned by YSnoopingRecord.get_time() has a variable resolution. This resolution is about 10% of the elapsed time.
As an application example of the YSnoopingRecord.get_message() function, we coded for you a small web page displaying in real time the messages listened to by the Yocto-RS232. This web page shows a red time line along which the messages are displayed. Messages from the incoming buffer are displayed in the top half and messages from the outgoing buffer in the lower half.
An HTML application to see what happens on a serial line
At the very bottom of the window, a quite simple interface allows you to:
- Select the YSerialPort to be used.
- Set the parameters of the said port. Don't forget to selectFlowControl=Snooping to perform snooping.
- Configure the time scale.
You start the capture by clicking on the play button and you stop it by clicking again on the same button. The button with a cross is used to erase the content of a capture. Note that if you change the browser display zoom level, the content adapts automatically.
How to use it?
You can download this application by clicking on this link. It's a small zip file. Unzip everything in a directory of your choice. Check that your Yocto-RS232 is actually connected, run the VirtualHub, and open the yoctosnoop.html file with a recent web browser.
One last thing
The YSerialPort.snoopMessages() function works not only in "snooping" mode, but also in the other modes. You can very well use it to debug transmissions that the Yocto-RS232 sends or receives directly.