Project setup - Windows

Installation steps for Windows.

Tested on Windows 11

It is possible to run the software in Windows, with a few extra steps.

Install Docker Desktop

Virtualization needs to be enabled

Check first if the PC has virtualization enabled.

Open the Task Manager.
Go to the performance tab and click on the CPU graph.
Check the Virtualization option at the bottom-right corner. It needs to be enabled or Docker will not run.

Not enabled? Try these instructions from Windows Support.

Download Docker Desktop and follow the interactive installation.

Install usbipd

This is needed to attach the USB sensors to the Windows Subsystem for Linux (WSL).

Open a terminal in administrator mode (right click and run as administrator) and install the usbipd software using the following command:

winget install usbipd

Maybe a confirmation window will pop up, follow the instructions and wait until it finishes.

Setup the software

Pull the project docker image

Open a new terminal (or use the previous one) and pull the project docker image:

docker pull aaronrpb/force-platform-app

Run a new docker container

Create a new container where the software will be running, with:

docker run -d --name example_app \
  --privileged -p 8501:8501 \
  aaronrpb/force-platform-app

Note

You can change the name example_app to any name you prefer.
Currently, it is recommended to use the --privileged flag. This is required to allow WSL to recognize the connected sensors. Another workaround could be adding temporal permissions to /dev/bus/usb/00x/00x paths with chmod 666, but this is not recommended as it gives full access to the device and the permission will be lost when the sensor disconnects.

Check if the container is running, going to http://localhost:8501/.

You will need to upload a custom configuration file with proper usb paths.

Do not try to connect sensors yet, it won't work unless you bind them to WSL. This will be the last step.

If the streamlit web-app is showing, stop the container with:

docker stop example_app

Or stop it from the Docker Desktop window, going to the Containers tab and clicking the stop icon.

Attach the USB sensors to WSL

Before starting the docker container, you will need to attach the sensors to WSL. Connect them to the PC and follow the steps.

Identify the sensors

Open a terminal in administrator mode and check the connected usbs with usbipd:

usbipd list

This will show up something like the following list:

Connected:
BUSID  VID:PID    DEVICE                                                        STATE
4-11   0db0:422d  Realtek USB2.0 Audio, Dispositivo de entrada USB              Not shared
4-12   0e8d:0616  RZ616 Bluetooth(R) Adapter                                    Not shared
4-15   1462:7d75  Dispositivo de entrada USB                                    Not shared
6-1    1532:0084  Razer DeathAdder V2, Dispositivo de entrada USB               Not shared
6-2    1b1c:1b40  Dispositivo de entrada USB                                    Not shared
7-1    06c2:003b  Dispositivo de entrada USB                                    Not shared
7-2    b58e:9e84  Yeti Stereo Microphone, Dispositivo de entrada USB            Not shared

Persisted:
GUID                                  DEVICE

Identify the BUSID and the VIP:PID from the sensors. This will be used for the bind/attach commands and WSL usb checks.

For example, in the provided list, BUSID 7-1 corresponds to a PhidgetBridge USB connection with four loadcell sensors.

If you have more than one USB connection, repeat the following steps for all sensors.

Bind the sensors

All the sensors we want to attach have to be binded first, with the --busid flag:

usbipd bind --busid 7-1

Now if we check the list again with usbipd list, bus 7-1 will be Shared at the STATE column:

Connected:
BUSID  VID:PID    DEVICE                                                        STATE
4-11   0db0:422d  Realtek USB2.0 Audio, Dispositivo de entrada USB              Not shared
4-12   0e8d:0616  RZ616 Bluetooth(R) Adapter                                    Not shared
4-15   1462:7d75  Dispositivo de entrada USB                                    Not shared
6-1    1532:0084  Razer DeathAdder V2, Dispositivo de entrada USB               Not shared
6-2    1b1c:1b40  Dispositivo de entrada USB                                    Not shared
7-1    06c2:003b  Dispositivo de entrada USB                                    Shared
7-2    b58e:9e84  Yeti Stereo Microphone, Dispositivo de entrada USB            Not shared

Persisted:
GUID                                  DEVICE

Attach the binded sensors

Once the sensors are with the Shared state, attach them to WSL with:

usbipd attach --wsl --busid 7-1

This will trigger the Windows USB unplug sound and also show some information in the command line from usbipd:

usbipd: info: Using WSL distribution 'docker-desktop' to attach; the device will be available in all WSL 2 distributions.
usbipd: info: Detected networking mode 'nat'.
usbipd: info: Using IP address 172.28.48.1 to reach the host.
usbipd: info: Firewall check not possible with this distribution (no bash, or wrong version of bash).

Check WSL USB lists

From the same terminal, enter to WSL (Docker Desktop must be open):

wsl

Check the connected usbs with lsusb:

lsusb

Something like the following will show up. Identify the connected sensors by their ID (those are the VIP:PID tags shown with usbipd list).

Bus 001 Device 001: ID 1d6b:0002
Bus 001 Device 002: ID 06c2:003b
Bus 002 Device 001: ID 1d6b:0003

In this example we can check that the PhidgetBridge is correctly attached. The VIP:PID was 06c2:003b, this corresponds with Bus 001 Device 002.

If you see all your sensors listed, they are correctly attached!

Are you connecting Taobotics IMUs?

To connect Taobotics IMUs you will need to do an extra step inside WSL. Check first if WSL has automatically assigned your IMUs to ttyUSB ports:

ls /dev/ttyUSB*

If it shows No such file or directory, your IMU drivers are not being recognized. You will need to load the kernel module cp210x for USB to UART Bridge usbs. Do not be scared, it is only one command inside WSL:

modprobe cp210x

Now if you check again with ls /dev/ttyUSB* you will see the recognized IMUs!

To leave the WSL interface, use the exit command:

exit

Detach and unbind sensors

It is not necessary to detach and unbind every time you want to disconnect the USB sensors from WSL. This is only needed if you want to release the device from WSL so that it is no longer in use, and Windows can take control of it again.

usbipd detach --busid 7-1
usbipd unbind --busid 7-1

Software usage instructions

Follow these steps to ensure proper sensor connectivity and optimal software functionality.

For more information about the software app features, check out the documentation within the software, at the homepage.

Start

Open Docker Desktop.
Connect sensors to PC.
Check in they are attached to WSL.
Start the docker container from the Containers tab on Docker Desktop, or use the docker start <container_name> command in a terminal.
Open the software app url (http://localhost:8501/) or other configured port/url.
Connect your sensors to the app.
Record data, check graphs and download it in CSV files.

Stop

Make sure you are not recording data from connected sensors.
Stop the docker container from the Containers tab on Docker Desktop, or use the docker stop <container_name> command in a terminal.
Disconnect the sensors or detach/unbind them (this is optional).

Update

You can check new updates from the DockerHub page or the GitHub repository.

If you where using a custom configuration file, you will need to upload it again.

Download your custom configuration file before removing the docker container.

The new updated container will always run with default settings and has no custom configuration file in it.

If you want to update the software to newer versions, follow these steps:

Open Docker Desktop and go to the Images tab. Click in the three vertical dots on the aaronrpb/force-platform-app actions column and click on the Pull option.
When updated, go the the Containers tab and remove the app container.
Create a new container opening a terminal and running the following command:

docker run -d --name example_app \
  --privileged -p 8501:8501 \
  aaronrpb/force-platform-app