eevengers/thunderscope

ThunderScope GitHub Repo

ThunderScope

Low-Cost Four Channel 1GSPS Oscilliscope using Thunderbolt/USB4 to stream data to PC for processing and display.

Join our development discord server

We are now at #thunderscope:matrix.org on matrix or #thunderscope:libera.chat on IRC as well!

Some older long-form documentation is on the Hackaday.io project page

Get the hardware through our crowdsupply page when we launch:

Catch up with these videos on the project:

TEARDOWN 2023 - Open Sourcing the Secrets of Oscilloscope Design

Hackaday Supercon 2023 - A Circuit to Measure Circuits: How do Oscilloscopes do it?

Teardown Session 39: ThunderScope

Quick Start Guide

These are instructions for the XDMA gateware, which is currently the most stable gateware and driver.

1. Install the XDMA driver for Linux or Windows
   • On Windows, first run Bcdedit.exe -set TESTSIGNING ON in administrator powershell and restart your computer
     • Then use the MSI installer, when asked if you want to use polling, click no
   • On Linux, run sudo make install in the xdma directory
     • Run make in the tools directory
     • Create a udev rule so you don't have to run everything acessing the hardware as root:
       • create /etc/udev/rules.d/70-thunderscope.rules file with the line ACTION=="add", SUBSYSTEM=="xdma", TAG+="uaccess"
     • With a TS connected, run sudo ./load_driver.sh in the tests directory
       • Output should be The Kernel module installed correctly and the xmda devices were recognized.
2. Build TS.NET.Engine using the build scripts
   • Dependences for build scripts on Debian/Ubuntu Linux: sudo apt-get install -y dotnet-sdk-8.0 libgdiplus
   • On Windows, should just need Visual Studio with the C# plugins
   • Copy appsettings.json and thunderscope.yaml into the same directory as the TS.NET.Engine application
3. Install ngscopeclient, following the instructions in their user manual
4. Run TS.NET.Engine and ngscopeclient
5. Add ThunderScope in ngscopeclient under Add -> Oscilloscope with "thunderscope" Driver, "Twinlan" Transport and "Localhost:5025:5026" for the Path

Troubleshooting

If you are getting under ~1000MB/s throughput on Linux, try turning off VT-d (Intel) or IOMMU/AMD-Vi (AMD) in BIOS or using "intel_iommu=off" in GRUB (Intel)

Baseboard Hardware

Revision	Label	Status	Location
Rev.1	N/A	DEPRECATED	Hardware/Altium/Thunderscope_E
Rev.2	N/A	DEPRECATED	Hardware/Altium/Thunderscope_Rev2
Rev.3	Alpha	DEPRECATED	Hardware/Altium/Thunderscope_Rev3
Rev.4	Beta 1	ACTIVE	Hardware/Altium/Thunderscope_Rev4
Rev.4.1	Beta 2	ACTIVE	Hardware/Altium/Thunderscope_Rev4.1

FPGA Module Hardware

Revision	Status	Location
TE0712	ACTIVE	Trenz Electronics TE0712 Module, 100T or 200T Varients
Rev.1	DEPRECATED	Hardware/Altium/FPGA_Module
Rev.2	ACTIVE	Hardware/Altium/FPGA_Module_Rev2 or Hardware/KiCad/FPGA_Module_Rev2

Firmware

We have two types of firmware, LiteX and XDMA. We are in the process of updating the LiteX firmware to work on the latest hardware, and we will use it moving forward. Until then, use the XDMA firmware if you are not working on LiteX.

TODO: Table of Beta Unit serial numbers with module types and firmware locations

Serial Numbers	Module Type	XDMA Firmware Location
TS0004, TS0006, TS0015	TE0712 100T	Firmware/XDMA/output/xdma_prj_100t_full.mcs
TS0007, TS0008, TS0011-TS0014	TE0712 200T	Firmware/XDMA/output/xdma_prj_200t_full.mcs
TS0009, TS0010, TS0016-TS0018	Custom Rev.2	Firmware/XDMA/output/xdma_prj_50t_full.mcs

Follow the instructions in the Software/xdma_driver_linux or Software/xdma_driver_win_src_2018_2 folders to install the XDMA linux or windows driver before proceeding with installing the rest of the software.

For LiteX developers, the Linux driver is stable. Windows and Mac drivers are in development.

Software

Our primary software is TS.NET, which takes in data from the hardware, triggers on it, and sends the triggered data over to ngscopeclient

thunderscope's Issues

Horizontal Time Bases

1 sample per nanosecond in single channel mode, each sample is 1 byte
10 horizontal divisions

All of these are in single channel, for dual and quad channel divide by 2 and 4 respectively
1ns/div - 10 samples per screen
2ns/div - 20 samples per screen
5ns/div - 50 samples per screen
10ns/div - 100 samples per screen
20ns/div - 200 samples per screen
50ns/div - 500 samples per screen
100ns/div - 1k samples per screen
200ns/div - 2k samples per screen
500ns/div - 5k samples per screen
1us/div - 10k samples per screen
2us/div - 20k samples per screen
5us/div - 50k samples per screen
10us/div - 100k samples per screen
20us/div - 200k samples per screen
50us/div - 500k samples per screen
100us/div - 1M samples per screen - We may need to down sample at this point
200us/div - 2M samples per screen
500us/div - 5M samples per screen
1ms/div - 10M samples per screen
2ms/div - 20M samples per screen
5 ms/div - 50M samples per screen
10ms/div - 100M samples per screen
20ms/div - 200M samples per screen
50ms/div - 500M samples per screen
100ms/div - 1G samples per screen
200ms/div - 2G samples per screen
500ms/div - 5G samples per screen
1s/div - 10G samples per screen
2s/div - 20G samples per screen
5s/div - 50G samples per screen
10s/div - 100G samples per screen

Waveform Math

The system should be able to add and subtract waveforms and display the result

CMake for Windows

Step 1: Write makefile to compile c++
Step 2: make works on Linux
Step 3: Windows doesn't have make. Write CmakeLists.txt for cmake
Step 4: cmake works on Linux
Step 5: test on Windows
Step 6: cmake fails to compile on Windows
Step 7: cry.

Triggers between buffers

Currently it doesn't properly check for triggers between buffers.

Each buffer has an extra sample that is used as the first sample from the next buffer. While the triggering methods all accommodate the extra sample, it never actually gets filled as the data come in.

This needs to be added somewhere before the triggers are computed in trigger.cpp

createThread and destroyThread should be moved into constructor and destructor

I don't really see a situation where we would want to create/destroy the thread and not the class itself as well.
It would also make it easier to maintain the code if we don't have to remember to run the extra function after/before creating/destroying.

This applies to all stages in the pipeline. (trigger, processor, postProcessor)

Cannot cross-compile addon.node for Windows

(See the branch SW/ratan-api-alpha)

The error I get is:

/mnt/c/Users/ratan/source/repos/DSO/Software/waveview/scope_link/src/EVLibrary.hpp:68:17: error: ‘mutex’ in namespace ‘std’ does not name a type
   68 |     static std::mutex lock;
      |                 ^~~~~
/mnt/c/Users/ratan/source/repos/DSO/Software/waveview/scope_link/src/EVLibrary.hpp:21:1: note: ‘std::mutex’ is defined in header ‘<mutex>’; did you forget to ‘#include <mutex>’?
   20 | #include <cstring>
  +++ |+#include <mutex>
   21 |

This is stupid because we already #include <mutex>. Probably related to posix v win32 threads.

Windows Support for C

All of the C needs to be compatible with Windows.
This is mostly for threads and mutexes.
Boost offers both of these and are fairly easy to use.

Voltage per Divisions

https://docs.google.com/spreadsheets/d/1lNDZ26gqocUVMz-UIqEJ7zu310GT8PDZG0Jh45Gnjpc/edit?usp=sharing

Vertical Widget

Each channel should have an ON/OFF button with the channel name on it [CH1, CH2, CH3, CH4]
They should be greyed out when OFF and the appropriate channel color when ON

Switch over to 1-2-5 scale from #70

Fine vs. Course control, Maybe a fine button or something to allow for voltages not in 1-2-5 sequence

Make offset control reference arrow on graph (low priority until API is set up)

Add AC/DC Coupling (maybe a button or set of buttons, these are the only two options)

Add x1 or x10 probe options (maybe use buttons, again these are the only two options)

Bandwidth Select (20MHz, 100MHz, 200MHz, 350MHz)
Depending on amount of channels used, these options will change
1 channel -> Up to 350
2 channel -> Up to 200
3 or 4 channel -> up to 100

Test ADC with 100 ohm Termination

This may fix the oscillations present in the samples

updateWindowSize is not thread safe

Someone could potentially call this function while the processor is currently running and copying samples into the persistence window.

Currently nothing calls this function.
It should be changed to stop the pipeline and flush all of the buffers because the user wont be changing this while also collecting samples.

Post processing from captured window to viewing window

Currently the C implementation doesn't preform our interpolation functions on the data (It was easier to work on the pipeline without the extra step).

This needs to be added back in as a step after the captured window is written to file.

Allow frontend to disconnect and reconnect

Keeping the back end alive will make some things easier to develop in the frontend.

will need to split the bridge core-loop into an inner and outer loop or something of the sort when disconnected

Remove test Redux components once Widgets are updated to support Redux connected components

In the initial install of Redux for the application, test components were created in order to demonstrate how Redux works. These need to be removed once we are able to implement Redux into core components of the application (like widgets).

Check performace of polling vs callback of C++ to electron data transfer

Packet passing has overhead and requires polling.
Implementing the data transfer though callbacks should improve performance.
We can look into this after we get a working prototype if we still need more performance.
I also need to learn how to actually run valgrind for profiling to be able to do this.

Create a template for global Redux store

Create a template of how we want to structure the global Redux store in the application.

Update the redux/reducers/index.tsx file to export the new global store and combine the appropriate reducers to these fields.

Get current master to work on Windows

Bottom Bar

Match info on bottom bar to what was set in the widgets

JS pulling more than 1 packet of data from socket at a time

Packets are sent individual from c++ and received as one in js.
Could just be the timing on the check-sleep loop in js
Will need to split data based on packet size when multiple are read at once.

Test both front ends

-Input Impedance
-Bandwidth and flatness
-Input overload protection

Last 4 bytes (every 2^14 bytes) not being printed to CSV

See PR#18

"Known bug - The last 4 bytes (every 2^14 bytes) are being missed when printing to csv. Why? idk. will be figured out once it's actually a immediate problem"

Samples before trigger point

Need to store X number of samples before the trigger point for displaying on the screen.
Currently it starts copying samples from the first sample involved in the trigger (ie: one of the 2 samples that make up the rising edge)
This will require holding onto buffers that don't contain triggers after they are processed.

Will we just ignore more overlap between trigger windows?
this would extend the minimum number of samples between consecutive triggers.

Automatic Measurements

The system should be able to make common amplitude & timing measurements on input data

Cursors

Adjustable cursors should be included in the interface to facilitate user measurements

Waveform Update Rate

The system must be capable of processing and displaying at least one million triggered samples per second

Git Documentation For API v2

need some docs for this

function names
demo file
usability tips

pls

Memory Depth

At least 1GB must be addressable by the system to store and readback sample data

Horizontal Widget

Switch over to 1-2-5 scale from #69

Fine vs. Course control, Maybe a fine button or something to allow for time bases not in 1-2-5 sequence

Value names are:
Timebase (s/div)
Horizontal Offset (s)

accept on a socket is a blocking call

If the bridge is deleted before a client connects, it will stay allive
This is because joining the thread will wait until it exits to collect the result

Asynchronous Logging

Current implementation uses std::cout for all logging.

In terms of performance, this is very expensive and should be replaced.

Boost has an async logger that should be looked into.

Update Install Guide (macOS, Linux)

include stuff like Boost, CMake, etc.

Should work with a "blank" OS.

PCIe Prototype PCB Design

Implement a State Management System

Research and implement an adequate state management solution for the application. For now, we should only worry about supporting basic UI functionality (adjusting values, style, counters, etc.)

Steps

• Investigate different state management solutions
  • Redux is a strong candidate
• Implement one of these solutions into our project
• Integrate basic UI functionality with the state management

Make Electron Pretty Again

This issue is being used to track all issues related to making the Electron app much more visually appealing. The list below should be updated with any major UX work needed, along with their associated issues (if applicable).

UX Improvements To Be Made

• Update the top bar of the application to use a custom dark mode implementation instead of the current white bar on top (similar to how Discord does it)
• Investigate a way of making the program look nice when running the program in a smaller window size/smaller resolution

Test limits of the graphing library

How many points can it graph while maintaining 60 fps?
Can it overlay a graph on top of a graph for persistence?

Trigger Widget

Should have three fields for now

Trigger Type [Rising Edge, Falling Edge]

Trigger Channel [CH1, CH2, CH3, CH4]

Trigger Level [Analog range based on what the vertical setting of the trigger channel is]

Two's Compliment Data

Because all software typically uses two's compliment, the ADC needs to be configured to output it.
Alexa confirmed that the option is available on the ADC.

Test PLL

Get phase noise numbers from spectrum analyzer

Investigate ways of accepting user input to the program

Currently, we are only using buttons to change the values of values/units. However, for uses such as fine tuning it would be nice to have a way for the user to type in a string/number to change something to a more specific value instead of having to rely on increasing/decreasing in set increments.

What needs to get done

• Implement a User Input test widget and integrate it with redux
• Create the correct state and reducers needed for accepting (and possibly parsing) user input
• Verify that we can take user input with no issues
• Begin implementing this logic into other widgets/settings as needed

Remove FTDI Stuff

Burn it all

Waveform Persistence

The displayed waveforms must be intensity graded based on how often they occur

Waveform Interpolation

Both Sin(x)/x and linear interpolation must be supported on triggered waveform data

Pipeline control logic

Need to be able to stop and restart the pipeline and flush out any data that is already partly processed.

Napi needs to be able to initiate this.

This can also be split up into the various elements (Changing window size, offset, etc) but they all need to be able to flush the pipeline.

Trigger Types

The system must support triggering on the rising and falling edges of the sampled data

Extra Trigger required past persistance count

In order for the code to register that the persistence buffer is filled, there needs to be another trigger. All of the tests currently have 5 triggers to fill the 4 window persistence buffer.

To test this, remove the 5th trigger edge from any of the tests and the program will not exit.

Should be able to fix this by adding an extra condition into the processor.cpp core loop.

Fix the Widget implementation to allow widgets to connect to Redux

Widget implementation needs to be updated/refactored to allow Redux connected components to exist within widgets.

Connect Redux to the appropriate widgets/blocks and allow them to access the store.

Once finished, work on issue #79.

Minimum System Requirements

The software should be fully functional on a modern computer with a quad core CPU and 8GB of RAM

My Poor CPU Performance

Leaving the program running for a while starts to bog down my computer to the point of affecting other programs.
Each stage of the pipeline and the 10 packet processors all are their own threads that sit idle most of the time. Each is polling for its respective input queue.

Valgrind should help narrow the biggest sinks down.

To reproduce give the test.js a while loop condition that will never be met and then just wait for things to slow down.

windows named pipe may never exit

I fixed this issue on linux sockets.
the bridge's destructor sets the tx_run and rx_run flags to false.
If reading from the pipe is a blocking call, it will never get to the next iteration of the while loop to check if it should exit
solution is to make sure the pipe is non-blocking

Need better error handling

See PR#18

"Beginning of error handling implementations (see this as we should talk Andrew).
Classes and Lambda expressions are starting to take shape. Be afraid."