Yoctobe Middleware – Deployment Guide for Linux and Windows

Linux

Linux deployment is straightforward. Open a terminal, navigate to the deployment folder, and run:

./deploy.sh

The script will check whether Docker is installed and offer to install it automatically if you are on Ubuntu. Once it completes, the middleware is running.

To stop it:

./stop.sh

That’s all there is to it on Linux.

Windows

Before you start – a word about virtualisation

Docker on Windows relies on a technology called WSL 2 (Windows Subsystem for Linux), which itself requires CPU-level virtualisation to be active. On the vast majority of machines sold since 2015, this setting (Intel VT-x or AMD-V) is already enabled in the BIOS by default, so you will never need to touch it. However, if Docker refuses to start even after following all the steps below, that is the first thing to check. Instructions for that are at the bottom of this guide.

Requirements

• Windows 10 or Windows 11
• Administrator rights on the machine
• An internet connection

Step-by-step deployment

Step 1 – Open a Command Prompt as Administrator

1. Press the Windows key, type cmd.
2. Right-click on Command Prompt and choose Run as administrator.
3. Click Yes if Windows asks for permission.

Step 2 – Navigate to the project folder

Type the following command, replacing the path with the actual location of the project on your machine:

cd C:pathtoyourprojectdeployment

For example, if the project is on your Desktop:

cd C:UsersYourNameDesktopyoctobedeployment

Press Enter.

Step 3 – Run the deployment script

deploy.cmd

Press Enter and let the script run. Here is what it does automatically:

• Checks whether the required Windows features (WSL and Virtual Machine Platform) are enabled, and enables them if they are not.
• Checks whether Docker Desktop is installed, and installs it via winget if it is not.
• Starts Docker Desktop and waits for it to be ready.
• Builds and starts the Yoctobe middleware container.

If the script asks you to reboot: This will only happen the very first time, if it had to enable Windows features that were previously off. Save your work, reboot, then open the Command Prompt as Administrator again and re-run deploy.cmd. The second run will go straight through without another reboot.

Step 4 – Verify it is running

Once the script finishes without errors, open your browser and go to:

http://localhost:1881

If you see the Yoctobe interface, the middleware is up and running.

Connecting serial / USB instruments

COM ports (RS-232 / RS-485)

The deploy script automatically detects any COM ports present on the machine and maps them into the container as /dev/ttyUSB0, /dev/ttyUSB1, and so on.

• If no COM ports were detected, the script will ask whether you want to continue anyway. Answer Y to proceed without instrument access, or N to cancel, plug in your device, and try again.
• To confirm which COM port your instrument is on, open Device Manager → Ports (COM & LPT).

USB devices that do not appear as COM ports

Some instruments connect via raw USB rather than a virtual serial port. For these, you need a tool called usbipd-win. Install it by running the following in your Administrator Command Prompt:

winget install usbipd

After installation, run:

usbipd list

Find your device in the list, note its BUSID (e.g. 2-3), then attach it:

usbipd attach --wsl --busid 2-3

Then redeploy (run deploy.cmd again) so the container picks up the newly attached device.

Stopping the middleware

stop.cmd

Or, if you prefer PowerShell:

.stop.ps1

Available endpoints

Troubleshooting

docker command not found Docker Desktop is not installed, or it was just installed and the terminal has not picked up the new PATH yet. Close the Command Prompt, reopen it as Administrator, and try again. If the problem persists, install Docker Desktop manually from https://www.docker.com/products/docker-desktop.

“Engine not reachable” or Docker Desktop is not starting Open Docker Desktop from the Start menu and wait until it shows Engine running in the bottom-left corner. Then run deploy.cmd again.

Container fails to start with a volume or /dev error Open Docker Desktop → Settings → General and confirm that Use the WSL 2 based engine is enabled. Then update Docker Desktop to the latest version.

Instrument not visible inside the container

• COM port: check Device Manager to confirm the port is listed and which number it has.
• USB: make sure you have run usbipd attach as described above, then redeploy.

Docker won’t start at all – possible BIOS issue If Docker Desktop reports that virtualisation is not available, you need to enable it in your BIOS:

1. Reboot the machine.
2. Enter the BIOS/UEFI setup (the key is usually F2, F10, Delete, or Esc – it appears briefly on screen during startup).
3. Look for a setting called Intel Virtualization Technology, VT-x, or AMD-V (it may be under an Advanced or CPU section).
4. Set it to Enabled.
5. Save and exit. Windows will boot normally and Docker should now start.

If you are unsure which key opens your BIOS, search online for your PC or motherboard model followed by “BIOS key”.