Find your problem by what you see. Each entry says what is probably wrong and what to do, in order. If you are not sure where to start, run the check in the next section: it looks at your computer and network in a few seconds and names the likely cause.
- Run the check first
- Installing and starting
- A band does not show up in the Studio
- What the band's light and screen mean
- Wi-Fi problems
- Firewall (Windows, Mac, Linux)
- The heatmap is flat or stuck
- Two bands, or the labeler, are not recognised
- Recording problems
- Camera problems
- Training problems
- Prediction problems
- Battery and charging
- Still stuck
openmuscle doctor prints one line per check, marked PASS, WARN or FAIL, with the fix underneath anything that is not a pass. It ends with the most likely reason a band is not showing up.
Open a terminal and paste the line for your computer (this is the one place the kit asks you to use one). The installer put the program in the OpenMuscle/app folder in your home folder:
| Computer | Open a terminal | Then type |
|---|---|---|
| Windows | Start menu, type PowerShell, press Enter |
& "$env:USERPROFILE\OpenMuscle\app\Scripts\openmuscle.exe" doctor |
| Mac | Press Command and Space, type Terminal, press Enter |
~/OpenMuscle/app/bin/openmuscle doctor |
| Linux | Press Ctrl, Alt and T | ~/OpenMuscle/app/bin/openmuscle doctor |
It is fine to run it while the Studio is open, and with the bands on and joined to your Wi-Fi so it can look for them. Windows may ask whether to let Python through the firewall while it runs: choose Allow.
You should see a list of lines, mostly PASS. If your own folder is somewhere else, replace the start of the path with it.
| If the line says | Go to |
|---|---|
Python version or Required packages or Web page files FAIL |
Installing and starting: run the installer again |
Data folder FAIL |
The folder cannot be written. Pick another with --data-dir, see your-data.md |
Browser page port (8000) FAIL or WARN |
Port 8000 is busy |
Sensor data port (UDP 3141) or Discovery port (UDP 3140) FAIL |
Another copy is running |
Network address FAIL |
Your computer is not on a network. Join your Wi-Fi |
Wi-Fi network WARN, "connected to a band's own setup network" |
Rejoin your normal Wi-Fi and forget the OM- network (wifi-setup.md) |
Firewall FAIL or WARN |
Firewall |
Self-test frame FAIL |
Security software is blocking Python. Allow it, then try again |
Internet for the 3D hand viewer WARN |
Only the 3D hand picture needs internet; see Camera problems |
Bands on the network WARN or FAIL |
A band does not show up |
You typed openmuscle and the computer says "not recognised" or "command not found". The program is installed in its own folder and is not on your computer's search path. Use the full path from Run the check first (for example & "$env:USERPROFILE\OpenMuscle\app\Scripts\openmuscle.exe" web on Windows), or just start OpenMuscle from its OpenMuscle shortcut (on Linux, from the applications menu or by typing openmuscle-start), which needs no typing.
OpenMuscle needs Python 3.10 or newer, which is free. On Windows the installer tries to install it for you; if it cannot, or on a Mac or Linux:
- Windows: download it from python.org/downloads, run the installer, and tick Add python.exe to PATH on its first screen. Then run the installer again.
- Mac: download the installer from python.org, or if you use Homebrew,
brew install python. - Linux:
sudo apt install python3 python3-venv python3-pip(Debian and Ubuntu), or your distribution's equivalent (the installer prints it).
Then run the OpenMuscle installer again. It is safe to run it again at any time; it repairs a broken install. If it stops with an error, the message says what to do, and a detailed log is in OpenMuscle/logs/install.log.
- Windows, "Windows protected your PC" (SmartScreen): click More info, then Run anyway. The file is safe when it came from the OpenMuscle repository.
- Mac, "cannot be opened because it is from an unidentified developer": right-click (or Control-click) the file, choose Open, then Open again in the dialog. If the file does not run at all, open Terminal, type
bash(with a space), drag the file into the window, and press Enter. - Linux, nothing happens on double-click: open a terminal in the folder and run
bash install.sh.
- The window that says OpenMuscle is running. must stay open. If you closed it, start OpenMuscle again.
- Use the address printed in that window (usually
http://localhost:8000). If the browser did not open by itself, copy the address into Chrome or Edge. - If there is no window at all, start OpenMuscle from the shortcut. The window prints the problem if it cannot start.
- Use Chrome or Edge for best results. Firefox and Safari are not tested.
Only one OpenMuscle can run at a time, because two would fight over the bands' data.
- If you see OpenMuscle is already running at http://localhost:8000, you already have it open. Find that window or browser tab. To stop it, close its window.
- If you see Port 8000 is already in use ... so using port 8001 instead, another program holds port 8000. OpenMuscle chose the next free port; use the address it printed.
- To pick a port yourself:
openmuscle web --port 8010. - If it says UDP port 3141 is in use, another OpenMuscle window (or another program) has the data port. Close the other window, then start again. On Windows,
netstat -ano | findstr :3141shows which program holds it.
Clicking inside the black OpenMuscle window can pause it (the title bar shows "Select"). Press Enter or Esc with that window selected, and avoid clicking inside it.
OpenMuscle asks Windows and macOS not to sleep from inactivity, but closing the laptop lid still puts it to sleep. Keep the lid open while recording. If your computer sleeps aggressively, plug it in and set Sleep to Never in Settings while you work.
You should see, a few seconds after the band joined your Wi-Fi, a row for the band with a heatmap. Instead you see No band found yet. On Windows, check the network profile first. The most common cause is a Wi-Fi network that Windows calls Public: the installer's firewall rule covers Private networks only, so the bands cannot reach your computer. Open Settings, Network & internet, Wi-Fi, the properties of your network (Windows 10: click its name), and under Network profile type choose Private (more in Firewall). Then check these in order:
- Is the band on and joined? Look at its light. A powered band always shows a faint glow, and a dark light means it is switched off (press the power button once). After joining it is green for 2 seconds, then it pulses every 3 seconds (waiting for a computer) or is steady orange (a computer is receiving). If it is still blinking blue, it is not on your Wi-Fi yet: see wifi-setup.md. (A band with a screen also shows
WIFI OKand then the heatmap, and tapping MENU shows its status page with its address. The kit bands have no screen, so use the light; the band's address is also in your router's list of devices.) - Is your computer on the same Wi-Fi? Check the Wi-Fi icon. A computer on the guest network, on another router, on a VPN, or still on the band's
OM-network cannot see the band. Turn off any VPN while you work. - Is the Wi-Fi 2.4 GHz and is it a normal network? See Wi-Fi problems. Guest networks and networks with a sign-in page hide devices from each other.
- Is the firewall blocking it? On Windows this is often the Public profile from the line above, or a missed firewall prompt. See Firewall.
- Wait 30 seconds, then use the search buttons. In the Studio, click Add a device by IP address under the band cards, then Scan subnet. If you know the band's address (shown on its status page, or on your router's list of devices), type it into the box and press the plus button.
- Restart the band. Turn it off and on with the power button, or unplug and replug USB-C, and wait for the green light (or
WIFI OKon a band with a screen). - Run
openmuscle doctor(above). The last line names the most likely cause.
If a band was found before and then disappeared, the Studio's band card shows how many seconds ago it last sent data. Check the band is on, charged, and in range of the router.
The full card is device-reference.md. In short:
| Light | Meaning | What to do |
|---|---|---|
| Faint glow, always (it can look white or yellow) | The band is powered on. The glow sits under every other pattern, so a powered band is never fully dark | Nothing |
| Dark, no light at all | The band is switched off | Press the power button once; the faint glow shows that it is on. If it stays dark, try another USB cable or port |
| Faint glow only, and it never blinks blue when you want to set up Wi-Fi | The band's setup network has not started. On battery alone the band cannot start its setup network | Plug the band into USB, then look again for the blue double blink. See wifi-setup.md |
| Blue, one blink per second | Setup mode: ready for Wi-Fi details | wifi-setup.md |
| Blue, two quick blinks then a pause | Setup mode on a band without a screen. This is the normal pattern for the kit bands, not a fault | Read the setup name and password from the sticker on the band, then follow wifi-setup.md |
| Blue, steady | Joining your Wi-Fi | Wait up to 20 seconds |
| Green, steady for 2 seconds | Joined your Wi-Fi | Nothing; it is working |
| Amber, fast blink | Joining failed, going back to setup | Check the Wi-Fi name and password |
| Amber, one blink per second | Battery low | Plug in USB-C |
| Amber, slow pulse | Wi-Fi was lost, still retrying | Check the router |
| Red, fast blink | The band recovered from a crash | Usually clears within a minute; if it stays, restart it |
| Magenta, blinking | MENU and SELECT are being held | Let go now to wipe the Wi-Fi settings, or hold to 3 seconds to do it |
| Short pulse every 3 seconds (blue, red, green or white) | Waiting for a computer to connect. The colour is the band's role: blue left, red right, green labeler, white not set | Open the Studio. White means no role yet; set it in the Studio and the band's colour follows within a moment. If the Studio says the band itself was not updated, check it is on the same Wi-Fi and pick the role again |
| Orange, steady | A computer is receiving its readings | Nothing; this is the normal working state |
| Orange with a cyan flash every 5 seconds | Same, with USB plugged in | Nothing |
| Cyan, slow breathing | Paused (you tapped SELECT) | Tap SELECT to resume |
| Green, slow breathing | Recording to its memory card (Wi-Fi is off) | Tap SELECT to stop |
| Purple, pulsing | Charge mode, charging | Wait; tap SELECT to leave |
| Purple, steady | Charge mode, battery full | Unplug, or tap SELECT |
Screens (only on a band that has a screen; the kit bands do not): WIFI SETUP (set up Wi-Fi), WIFI FAILED (it could not join, see the reason on the next line), WIFI OK with an address (joined), PAUSED, CHARGING, RECORDING, and LOW BATTERY. Without a screen, the light patterns above say the same things.
- Power button (the switch at the top edge): a short press switches the band on, and a short press again switches it off. The faint glow shows which one your press did: lit means on, dark means off. How the press feels, and whether a press while USB is plugged in switches it off, is still to be confirmed on a band; if it will not switch off, unplug USB-C first.
- MENU and SELECT: the two buttons the band itself reads. Hold MENU for 2 seconds for charge mode, tap SELECT to leave it (or to pause and resume), and hold both together for 3 seconds to forget the Wi-Fi.
- The switch printed BOOT: restarts the band, like a reset button. It does not erase your Wi-Fi settings.
- The switch printed SW_RST1 at the bottom left: not used in normal use. Holding it while pressing BOOT puts the chip in download mode so that a stuck board can be reflashed. If you did that by accident, press BOOT alone to restart.
- The charger light: the charger chip drives a small light of its own on the board. Its colour is not yet confirmed, so rely on the band's status light for charging (see Battery and charging).
This is about Method 1 in wifi-setup.md: the Studio gives the band your Wi-Fi down its USB cable. Find what you see in the first column.
| What you see | What is wrong | What to do |
|---|---|---|
| Looking for a band on the USB cable... and it never turns into Found Band ...; or No band found yet | The computer cannot see the band on USB. Most often the cable only charges (it has no data wires), is not pushed in at both ends, or is plugged into a hub or a charger | Use the cable that came with the kit, which carries data. Push it in at both ends, use a USB port on the computer itself, and try another port. A data cable is needed: a charge-only cable lights the band but is never found |
| A band is plugged in but is not answering | The band is on USB but is not listening. A band that has sat on USB for a few minutes with nothing talking to it can stop answering | Unplug the cable and plug it back in (or press the BOOT button), then try again |
| More than one band is plugged in | Two bands are on USB, and the page cannot know which one you mean | Unplug all but the one you are setting up, or choose it in the list. The last six characters of the name match the Setup Wi-Fi line on the band's sticker |
| Could not open the USB port | Another program has the band open, such as a serial monitor or a flashing tool, or the cable came out | Close the other program, unplug the cable, plug it back in, and try again |
| Could not open the USB port, and it says this account is not allowed to use USB serial devices (Linux only) | Linux keeps USB serial devices for the dialout group, and your account is not in it |
In a terminal run sudo usermod -a -G dialout $USER (on Arch Linux the group is uucp), log out and back in, then try again |
| The band could not save the Wi-Fi details | The band received them but could not store them | Unplug the cable, plug it back in, and try again. If it keeps happening, use the band's own Wi-Fi instead (Method 2 in wifi-setup.md) |
| This band's software does not know how to be set up over USB | The band has older software than this page expects | Use the band's own Wi-Fi instead, or ask for a firmware update |
| It said Saved on the band but the band never appears | The band could not join your Wi-Fi (wrong password, 5 GHz only, a sign-in page, or a guest network) | Click Start over with this device when the list opens, retype the password with Show turned on, and go through the list in wifi-setup.md |
It could not join. Its light shows an amber fast blink and then the blue setup pattern again. A band with a screen shows WIFI SETUP and, on its top line, LAST TRY FAILED and a reason: check password (retype it), network not found or 5 GHz (check the name, move closer, use a 2.4 GHz network) or join timed out (check the router). Run wifi-setup.md again. Use Show in the wizard to see what you typed.
Hold MENU and SELECT together for 3 seconds. The light blinks magenta, and when you let go at 3 seconds the band forgets its Wi-Fi and goes back to the blue setup pattern (WIFI SETUP on a band with a screen). Its setup name and password are still the ones on its sticker. Then run the setup again.
That is expected while you are joined to the band's own network. Rejoin your normal Wi-Fi when the wizard tells you to, and forget the OM- network afterwards.
Check, in order: you are joined to the band's OM-flexgrid-... network (not your normal one); you typed http://192.168.4.1 with http, not https; you turned off mobile data on a phone and any VPN on a computer; the USB cable is plugged into the band (setup mode does not start on battery alone); and the band's light is still blinking blue (setup mode). On a phone, answer yes if it asks to stay connected to a network without internet.
Bands cannot join 5 GHz. Most routers broadcast a 2.4 GHz network too, sometimes under the same name. Check your router's settings, or use a phone hotspot (iPhone: Personal Hotspot with Maximize Compatibility on; Android: choose the 2.4 GHz band).
Bands cannot sign in to a web page, and guest networks keep devices apart. This applies to many hospital, school, hotel and office networks. Use your phone as a hotspot, or a network you control. When a guest network or router setting keeps devices apart ("client isolation" or "AP isolation"), the doctor says: "the band is announcing itself, but this computer cannot connect to it".
Look at its light: green for 2 seconds after joining, then a pulse every 3 seconds or steady orange. The Studio also shows a band card for it, and the band's address is in your router's list of devices. (A band with a screen shows WIFI OK and an address; tap MENU to see it again.)
A firewall can stop the bands' readings reaching your computer. OpenMuscle needs incoming UDP on two ports: 3140 (bands announcing themselves) and 3141 (the readings). Allowing only one of them leaves the bands invisible or silent. Your computer usually asks the first time; if you chose Cancel or Block, fix it now.
- Easiest: in PowerShell run
& "$env:USERPROFILE\OpenMuscle\app\Scripts\openmuscle.exe" firewall. It shows the rule it will add, asks, and only then opens the normal Windows administrator prompt. Answer Yes. - A rule applies to one network type. If Windows calls your Wi-Fi Public, a Private-only rule does nothing, and this is the most common reason bands are not found. Change the network to Private: Settings, Network & internet, Wi-Fi, open the properties of your network (Windows 10: click its name), and under Network profile type choose Private. Or run the same command with
--publicadded. - Or add the rule yourself, in an administrator PowerShell:
New-NetFirewallRule -DisplayName "OpenMuscle UDP 3140-3141" -Direction Inbound -Protocol UDP -LocalPort 3140,3141 -Action Allow -Profile Private,Domain. - Antivirus programs with their own firewall (not Windows Security) need the same two ports allowed for Python.
- When macOS asks Do you want the application to accept incoming network connections?, click Allow. Allow Local Network access too if System Settings asks.
- If you missed it: System Settings, Network, Firewall, Options, and allow incoming connections for Python, or turn the firewall off while you set up.
- System Settings, Privacy and Security, Local Network: make sure Terminal (or Python) is switched on.
If a firewall is on, allow the two ports: sudo ufw allow 3140:3141/udp (Ubuntu), or sudo firewall-cmd --add-port=3140-3141/udp --permanent then sudo firewall-cmd --reload (Fedora). Then start OpenMuscle again.
You should see PASS Firewall in openmuscle doctor, and the band appearing in the Studio within about ten seconds.
You should see the grid change colour when you press on the band. If it does not:
- Everything is black and nothing reacts to pressing. The band is not touching the skin, or the strap is loose. Refasten it snug (band-fit.md) and press again. If the band card says it has stopped sending (a number of seconds in red instead of
live), see A band does not show up. - It shows the colours but they never move. The heatmap froze because the page lost its connection (the connected badge top right says disconnected). Reload the page; check the OpenMuscle window is still open.
- The whole grid is bright with your arm relaxed. The band is too tight, or a fold in the band presses on the skin. Loosen it and lay it flat.
- One cell is always bright or always dark. One sensing cell may be damaged or misaligned. If the others react, carry on, but note it in your session notes.
- It is jumpy. Fasten the band evenly and hold still for a moment; a loose strap that shifts gives jumpy readings.
- Only some bands show. See below.
- Each band has its own name on its card (
flexgrid-and six characters). The Studio needs to know which arm each is on. On each band's card use the role menu to choose left or right. Recording is blocked with "Tell me which arm each band is on" until you do, and with "Both bands are set to the same arm" if you chose the same side twice. - A band with a white pulse has no role yet.
- A band that is quiet for more than a couple of seconds shows its age in seconds. Recording is blocked with "A band has stopped sending data. Check it is on and charged."
- The LASK5 labeler (optional hardware) needs to be on the same Wi-Fi. If its bars stay flat, press a piston and check the Finger data from menu says the LASK5, not the camera.
The sentence next to the Record button says what is wrong:
| It says | What to do |
|---|---|
| No band found yet. Turn your band on and wait about 10 seconds. | On Windows, first check that your Wi-Fi is set to Private (Settings, Network & internet, Wi-Fi, your network, Network profile type); a Public network hides the bands. Then see A band does not show up |
| The camera is not on. Open the Camera panel on this page, press Start camera and hold your hand up. | See Camera problems |
| The camera has stopped sending hand data. | Keep the Camera panel on this page open and the tab in front |
| Tell me which arm each band is on. | Set left or right with the role menu on each band's card |
| The finger labeler (LASK5) is not sending data. | Switch it on, check it is on the same Wi-Fi, or change Finger data from |
After you stop, the take gets a quality word (Good, Check or Bad) with the reason in plain words:
| Reason | Fix |
|---|---|
| Too short to train on | Record at least 10 seconds; 30 seconds or more is best |
| The band is not picking up pressure | Make sure it is snug on your arm, then record again |
| No finger data arrived / Almost no finger data came through | Check the camera or labeler is on and your hand is in view, then record again |
| Your hand barely moved | Open and close your hand through the whole take |
| Hand tracking lost your hand | Keep your hand in view of the camera |
A take that was recorded with No labeler is saved but cannot be used to train a model.
The Camera panel says in plain words what happened. The causes and fixes (camera blocked or busy, no camera found, tracker download, left and right swapped) are in the table in webcam-labeling.md. In short:
- Click the camera icon in the browser's address bar and choose Allow; on Windows also check Settings, Privacy and security, Camera; on a Mac, System Settings, Privacy and Security, Camera.
- Close Zoom, Teams, FaceTime and other tabs that use the camera.
- The first time the camera starts it downloads the hand tracker (about 17.6 MB), so it needs internet once. After that,
openmuscle assets fetchkeeps a copy for offline use (the installer does this when you are online). - The camera only works at
http://localhost:8000, on the computer that runs OpenMuscle. - The finger bars stay flat (the labeler looks dead). The tracker cannot see a hand: hold one hand up, palm toward the camera, all fingers visible, in good light, about an arm's length away. A flat line while your hand is clearly in view usually means the browser tab was in the background, which pauses the camera; keep the Camera panel inside the Studio page and the page in front. With the optional LASK5, flat piston bars mean the labeler is not on the same Wi-Fi or its pistons are not being pressed.
-
The Train button is greyed out. Tick at least one take in the Captures list first.
-
"Could not train yet" with a sentence. The sentence says what is wrong. The common ones:
It says What to do There are only N usable samples ... A model needs at least 150 samples (roughly 10 seconds) Record a longer take, about a minute of slowly opening and closing each finger These recordings have no finger labels Record again with the camera or labeler turned on The finger labeler never moved Check it can see your hand, and move your fingers through the whole take The band was not touching the arm Check the band sits snug against the skin and record again Every recorded row has a gap in the finger labels Keep your hand fully in view and record again The left and right bands were never recorded at the same moment Train one hand's takes at a time -
The recordings do not match. Do not mix takes from different kinds of band (older 12-sensor and current 60-sensor) or different labelers (camera and headset), because their columns differ. Train them separately.
-
The result says Weak or Not working yet. The model could not predict finger movement from a recording it had never seen. Record more takes with slow, clean open-and-close movements, rest between them, and keep the band in exactly the same place (band-fit.md). Two or more separate takes give a fairer score than one.
-
A warning about different participants or sessions. A model works best for the person and the band position it was trained on. Train one person and one session at a time.
- Predict says "no model yet, train first". Train a model first.
- A banner says the model may not match. The model was trained for another person, or for a different band than the one on that arm. Train a new model for this person and these bands, or press Predict to run it anyway.
- The predicted bars do not move. Check the band card is live and the model's result card said Fair or Good. A Weak model barely moves.
- Predictions are wrong after taking the band off. Put it back exactly where it was; a model learns one position (band-fit.md).
- Plug in USB-C. The band charges whenever USB is connected. For the fastest charge, hold MENU for 2 seconds to enter charge mode (the Wi-Fi turns off and the light pulses purple, then turns steady purple when full; a band with a screen also says
CHARGING). Leaving charge mode restarts the band. - If it does not charge, try another cable and another USB port or a phone charger.
- Setting up Wi-Fi needs the USB cable plugged in: on battery alone the band cannot start its setup network. After that it runs on battery.
- A band that sits on USB for five minutes with no app listening stops answering the USB check tool from the firmware repository. Press BOOT or unplug and replug the cable to bring it back.
- A band with a low battery shows an amber blink (once a second), and
LOW BATTERYon its screen if it has one.
Make a report to send to the maintainers, then open an issue at github.com/Open-Muscle/OpenMuscle-Software/issues.
- Run
openmuscle doctor --report(the command from Run the check first, with--reportadded). It writes a file calledopenmuscle-report.txtin the folder you are in. The report contains versions and the check results only. It never contains Wi-Fi names, passwords or recordings. - In the issue, include:
- the report file,
- your computer (Windows, Mac or Linux, and the version),
- what you did, what you expected and what happened instead,
- what the band's light shows (and its screen, if it has one),
- for a band that will not appear: whether your Wi-Fi is 2.4 GHz, whether it is a guest or hotel-style network, and whether the firewall prompt was answered.
- Do not attach recordings, and do not put anyone's name in the issue. Describe the problem; you can send a recording separately if asked (your-data.md).