{"id":135,"date":"2017-06-19T21:45:26","date_gmt":"2017-06-19T19:45:26","guid":{"rendered":"http:\/\/blog.ilialex.gr\/?p=135"},"modified":"2017-06-21T09:29:23","modified_gmt":"2017-06-21T07:29:23","slug":"decoding-serial-busses-from-digital-oscilloscope","status":"publish","type":"post","link":"http:\/\/blog.ilialex.gr\/?p=135","title":{"rendered":"Decoding Serial Busses from Digital Oscilloscope"},"content":{"rendered":"

Introduction<\/span><\/span><\/b><\/p>\n

\u00a0<\/span><\/span>Using a Digital Oscilloscope was a premium tool in the past; although professional equipment is still a high cost if considered for amateur use, the cost of equipment has fallen the last years allowing more people to get these instruments.<\/span><\/span><\/p>\n

\u00a0<\/span><\/span><\/p>\n

In today\u2019s world of microcontrollers and IoT, it is not uncommon to debug serial low-speed buses, like RS232, SPI and TWI (I2C). Hobbyists and professionals need to decode manually each bit knowing the protocol. This is natural to do if you are at the first debugging stages where you need to check electrical integrity on a new design, but it gets tedious if you need to concentrate on the protocol. Purchasing a decoding module for these oscilloscopes increase the cost and many times is not an option for a one off project.<\/span><\/span><\/p>\n

\u00a0<\/span><\/span><\/p>\n

The good thing with such instruments is that they usually provide some connectivity with serial, ethernet or USB connection. Usually apart from any web based control you have the option to program the instrument through the SCPI interface. You may use any language you want if you want to access the instrument as long as you have installed the relevant VISA libraries\/drivers like National Instrument\u2019s NIVISA, or the Tektronix TekVISA (see below for links). <\/span><\/span><\/p>\n

\u00a0<\/span><\/span><\/p>\n

For those unfamiliar with SCPI\u00a0(Standard Commands for Programmable Instruments<\/span><\/u><\/a>), it is a standard protocol to access instruments initially based on IEEE-488 connection. Later on as more instruments used serial or ethernet connection, the required GPIB card has became obsolete and made things easier and more straight forward. The instructions available are mostly universal, but each instrument can complement these with any extensions needed to support the features unique on it.<\/span>\u00a0\u00a0 <\/span><\/span><\/p>\n

\u00a0<\/span><\/span>Examples of SCPI commands:<\/span><\/span><\/p>\n

*IDN?\r\nACQUIRE:STATE STOP\r\n<\/code><\/pre>\n
I started programming many instruments that way in the past using C\/C++ but after switching to python I forgot about any other language in the host machine. Scripting languages offer an easy go process especially for string manipulation etc. <\/span><\/span>For this reason I wrote a python script to capture signals from the oscilloscope and decode them.<\/span><\/span><\/p>\n
In summary to access the SCPI port of a connected instrument you need the following:<\/span><\/span><\/p>\n
1. Python Interpreter (code is written in 2.7 generation) (<\/span>https:\/\/www.python.org\/downloads\/<\/span><\/u><\/a> ) <\/span><\/span><\/p>\n
2. TekVISA\/NIVISA (or any other corresponding VISA library) package (<\/span>https:\/\/www.ni.com\/visa\/<\/span><\/u><\/a> , <\/span>http:\/\/uk.tek.com\/oscilloscope\/tds7054-software<\/span><\/u><\/a> )<\/span><\/span><\/p>\n
3. PyVISA module (<\/span>https:\/\/pyvisa.readthedocs.io\/en\/stable\/<\/span><\/u><\/a> \u00a0<\/span>)<\/span><\/span><\/p>\n
4. The Capture\/decode python script<\/a>.<\/span><\/span><\/p>\n
Now under Windows you may use the executable which is a compiled python script (with GUI2Exe). In this case you will need only the VISA installation and the tool itself (no need for python+pyvisa as these are included in the compiled program).<\/span><\/span><\/p>\n
 <\/p>\n
How it works<\/span><\/span><\/b><\/p>\n
\u00a0<\/span><\/span>The tool captures the signals from the oscilloscopes in a CSV file. As I use an old TDS3012B DPO from Tektronix, I only have 2 available channels to capture. This is fine for capturing RS232 or TWI signals, but for SPI you may need to perform multiple runs to capture 2 data lines and CS along with the clock, with you ending up changing probes for each run, but this is better from nothing. <\/span><\/span><\/p>\n
Oscilloscopes with more channels would of course capture more signals and avoid this hick-up. The script is made and tested on this particular oscilloscope, but it should work in most other instruments maybe with slight modifications. If you need to capture more channels then you still need to modify the script to save the extra channels on the CSV and in addition to add to the SPI decode module the extra traces to decode. But this is why we have open source right?<\/span><\/span><\/p>\n
Keep in mind that the script decodes from the CSV file (and not directly from the instrument). Thus if you have old (or test) captures you may instruct it to use these instead of accessing an instrument. This helps for off-line decoding or testing the script.<\/span><\/span><\/p>\n
\u00a0<\/span><\/span>After the signals are captured, the script performs a thresholding according to the set logic standard like TTL, CMOS, LVCMOS etc. <\/span><\/span><\/p>\n
\u00a0<\/span><\/span>Then it decodes the signal according to the requested protocol and displays the decoded output on screen.<\/span><\/span><\/p>\n
To keep the script simple, we setup the oscilloscope manually to capture the signals fully (with the required time-span, sampling etc) and we leave it running. Triggering should be to Normal mode (not Auto). When we need to capture the waveform we can either run the script which stops acquisitions or we can stop manually and still use the script to acquire and decode the signals.<\/span><\/span><\/p>\n
\u00a0<\/span><\/span>Let\u2019s see some examples.<\/span><\/span><\/p>\n
RS-232 Decoding<\/strong><\/p>\n
Running the command:<\/p>\n
\r\nDSOCapture.py -b RS232 -l TTL -a 115200 -i CaptureRS422_LVCMOS.csv -n 0\r\n<\/code><\/pre>\n
We decode a file with data already acquired to a file.<\/p>\n
We need to define the baud rate, the voltage level and polarity (positive or reversed).<\/p>\n
\"RS232<\/a>
RS232 Command Prompt Capture Example<\/figcaption><\/figure>\n
The decoder displays the resulted characters along with the Start-Stop and Parity bits. In addition a VCD file is exported that we can view with GTKWave.\u00a0<\/span><\/p>\n
\"rs232_wave\"<\/a>
RS232 Waveform Capture Example<\/figcaption><\/figure>\n
\u00a0<\/span><\/span><\/p>\n
TWI Decoding<\/span><\/span><\/strong><\/p>\n
In TWI mode the parameters are more simple as TWI is clocked so we do not need to define sampling period for each character.<\/p>\n
\r\nDSOCapture.py -v -b I2C -i CaptureI2C.csv\r\n<\/code><\/pre>\n
\"twi_dos_capture\"<\/a>
TWI Command Prompt Capture Example<\/figcaption><\/figure>\n
Again the results are shown in the Command Prompt, showing Start-ACK-Stop conditions.
\nIn addition the VCD file provides a graphical view.<\/p>\n
\"twi_wave01\"<\/a>
TWI Waveform Capture Example<\/figcaption><\/figure>\n
 <\/p>\n
\"twi_wave02\"<\/a>
TWI Waveform Capture Example Detail<\/figcaption><\/figure>\n
\u00a0<\/span><\/p>\n
SPI Decoding<\/span><\/span><\/strong><\/p>\n
\u00a0<\/span><\/span>
\nIn this example we acquire the signal from the instrument (which is the more common way to do it). Every acquisition will store the .csv file with the data, if you need it. However you will need to copy it since the next acquisition will overwrite it.<\/p>\n
DSOCapture.py -v -b SPI -t 3 -visa -i TCPIP::192.168.2.226::INSTR -f\u00a0capture.csv\r\n<\/code><\/pre>\n
\"spi_dos_capture\"<\/a>
SPI Command Prompt Capture Example<\/figcaption><\/figure>\n
\u00a0<\/span><\/span><\/p>\n
\"spi_sd_wave\"<\/a>
SPI Waveform Capture Example<\/figcaption><\/figure>\n
 <\/p>\n
\u00a0<\/span><\/span>\u00a0<\/span><\/span><\/b><\/p>\n
Development Methodology<\/span><\/span><\/b><\/p>\n
Now the interesting thing is that I used TDD (Test Driven Development) methods to create this script. To help me in this process I used the pytddmon.py script. So when developing you just need a command prompt or shell in the directory holding the script and run pytddmon.py (should be at the same directory). See picture below.<\/span><\/span>\u00a0<\/span><\/span><\/p>\n
\"PyTDDmon<\/a>
PyTDDmon View<\/figcaption><\/figure>\n
 <\/p>\n
\"Python<\/a>
Python Test Code<\/figcaption><\/figure>\n
 <\/p>\n
You may download pytddmon from here<\/a>. Alternatively you may use:<\/span><\/span><\/p>\n
pip install pytddmon<\/code><\/pre>\n
\u00a0<\/span><\/span><\/p>\n
Next thing is that I created the test cases for each module. Initially I used real data captured on my oscilloscope or used similar values to test the various cases. For example thresholding the incoming stream is more challenging than just compare and output a logic value. As you pass through the transition phase from 0-1 or 1-0 then some values may trigger multiple transitions on each edge. In this case you need to perform hysteresis ( link ) to avoid it (as the electronics do as well). <\/span><\/span><\/p>\n
\u00a0<\/span><\/span>After the signals have been interpreted to logic levels (or edges as well, as TWI uses the edges), then the thresholded outputs are passed to the corresponding serial bus analyzer.<\/span><\/span><\/p>\n
\u00a0<\/span><\/span><\/p>\n
Limitations<\/strong><\/p>\n
The script does work well but there are limitations mainly due to the hardware (Digital Oscilloscope) which is worth to mention.<\/span><\/span><\/p>\n
RS232<\/span><\/span><\/em><\/p>\n
The problem with RS-232 is that it is an asynchronous transmission. To better state the problem, there is no clock transmitted or derived from the data. It is assumed that the receiver has a similar clock within a certain range to capture and decode the transmission.<\/span><\/span><\/p>\n
If you need to capture a long stream of bytes and the scope does not have big memory you will find yourself limited on what can be captured. As the scope’s memory is not sufficient to hold a longer time period with much detail the decoded data may be scrambled (usually after a few bytes). To overcome this you may need to decrease the time span of the data or use an instrument with sufficient memory capacity to hold accurately the signal transitions.<\/span><\/span><\/p>\n
TWI<\/span><\/span><\/em><\/p>\n
This kind of bus uses edge signalling to determine certain protocol states (like Start\/Stop conditions). If the sampling of the scope is not sufficient you may get bad decoding of the signals. Although not so severe as RS-232 protocol, this will happen only if you stress the instrument.<\/span><\/span><\/p>\n
SPI<\/span><\/span><\/em><\/p>\n
SPI bus is a clocked transmission so sampling is not much an issue as in the other protocols. However because you usually need\u00a0three lines (SCK, MISO, MOSI), you need extra effort to read all lines with a two channel scope. As this script was built around TDS3012B, it captures only two channels. If you have an instrument with more channels available I would recommend to modify the script and capture the extra channels. <\/span><\/span><\/p>\n
\u00a0Summary<\/span><\/span><\/strong><\/p>\n
Improvements to the script can be performed, but as I am busy doing other things, I currently do not plan to do any additions. In any case any ideas are welcome and at some point may integrate them.<\/span><\/span><\/p>\n
I created this script some time ago, initially for TWI, then I added RS232 and finally the easiest part SPI.\u00a0I completed the whole script in about a two week time (with full functionality) and it was pretty easy. If I had to work without TDD, I would need to capture all the possible variations on my scope and debug a much larger codebase at the time.\u00a0<\/span><\/span><\/p>\n
\u00a0You may find a compiled Python executable here<\/span><\/u><\/a><\/span><\/span><\/p>\n
You may find the source tree in BitBucket<\/span><\/u><\/a>.<\/p>\n
 <\/p>\n
CodeProject<\/a><\/div>\n","protected":false},"excerpt":{"rendered":"
Introduction \u00a0Using a Digital Oscilloscope was a premium tool in the past; although professional equipment is still a high cost if considered for amateur use, the cost of equipment has fallen the last years allowing more people to get these instruments. \u00a0 In today\u2019s world of microcontrollers and IoT, it is not uncommon to debug … Continue reading Decoding Serial Busses from Digital Oscilloscope<\/span> →<\/span><\/a><\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4],"tags":[17,13,16,15,18,12,14],"class_list":["post-135","post","type-post","status-publish","format-standard","hentry","category-methods","tag-decode","tag-python","tag-rs232","tag-spi","tag-tds3012","tag-tektronix","tag-twi"],"_links":{"self":[{"href":"http:\/\/blog.ilialex.gr\/index.php?rest_route=\/wp\/v2\/posts\/135","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/blog.ilialex.gr\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/blog.ilialex.gr\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/blog.ilialex.gr\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"http:\/\/blog.ilialex.gr\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=135"}],"version-history":[{"count":20,"href":"http:\/\/blog.ilialex.gr\/index.php?rest_route=\/wp\/v2\/posts\/135\/revisions"}],"predecessor-version":[{"id":194,"href":"http:\/\/blog.ilialex.gr\/index.php?rest_route=\/wp\/v2\/posts\/135\/revisions\/194"}],"wp:attachment":[{"href":"http:\/\/blog.ilialex.gr\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=135"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/blog.ilialex.gr\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=135"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/blog.ilialex.gr\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=135"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}