Skip to content

Conversation

@mutatrum
Copy link
Collaborator

@mutatrum mutatrum commented Dec 9, 2025

This PR adds support for Ethernet-over-USB with USB NCM, which is an existing USB standard. It doesn't need drivers, custom software or custom hardware. It works on all Bitaxe devices with a USB port.

It adds a Network Mode dropdown on the Network Configuration page, to enable it:
image

The network mode is exclusive, so either Wi-Fi or Ethernet-over-USB. In the latter, the Wi-Fi module is still initialized for the setup Access Point.

After enabling this, and rebooting the device, the host computer will detect a new network device:
image

By default, internet it not shared to this new connection - for obvious security reasons - and to get the bitaxe connected, this needs to be configured. On Ubuntu, it's a simple configuration on the IPv4 tab of the network settings:
image
For IPv6 the same option is available.

For Windows and MacOS I assume there are similar options available. It is persisted for the device, so unplugging and plugging it back into another port works. Rebooting the host and it reconnects. The number of devices is limited to the amount of USB ports and space in the IP range.

After this, the device is connected over ethernet:
image

With this setting, the device is only accessible on the host machine, as the host machine gives it a new IP address on a different range. It is possible to configure the host with a DNS bridge, at that moment the device will get an IP address from the LAN range and it will be accessible for other machines on the LAN as well.

As this PR uses TinyUSB for the USB driver, if USB Ethernet is enabled, the hardware USB-PHY, repsonsible for console logging and the JTAG, is disabled. This is how the hardware works. TinyUSB also exposes serial logging, so after a brief disconnect, the logging over USB will resume. However, the JTAG is only available in the hardware USB-PHY, which cannot be re-enabled if TinyUSB is initialised. To be able to flash new firmware over USB, the device has to be put into bootloader mode by rebooting with the BOOT button pressed.

A follow-up PR could be to either write a guide or a firmware image for a Raspberry Pi to be configured as a DNS bridge.

@mutatrum mutatrum changed the title USB Ethernet Ethernet-over-USB Dec 9, 2025
@github-actions
Copy link

github-actions bot commented Dec 10, 2025

Test Results

23 tests  ±0   23 ✅ ±0   0s ⏱️ ±0s
 1 suites ±0    0 💤 ±0 
 1 files   ±0    0 ❌ ±0 

Results for commit 332f048. ± Comparison against base commit d647eb8.

♻️ This comment has been updated with latest results.

@duckaxe
Copy link
Collaborator

duckaxe commented Dec 10, 2025

Looks nice. I just added little UI fixes: mutatrum#8

Another thing: We should hide the Wi-Fi RSSI option from dashboard statistics if networkMode == usb.

@mutatrum
Copy link
Collaborator Author

Merged, thanks again!

Another thing: We should hide the Wi-Fi RSSI option from dashboard statistics if networkMode == usb.

Not sure how difficult that is. There's other ones as well, f.e. fan2rpm, and Temp2 is missing. Probably needs it's own PR.

@STSMiner1
Copy link
Contributor

This PR is going to cause problems for some.

I've tried to get this to work with more than one Bitaxe device connected to the PC (Windows 10) via a USB cable for each and failed to get it to work with ICS or via a bridge within Windows 10, Ethernet 2 and the Network Bridge have a status of "Network cable unplugged" when bridging the two Bitaxe network devices (Ethernet 2 & Ethernet 3) to create a virtual network, it fails, so not able to use ICS that way either.

ICS will work with one device but not two or more.

Using a USB hub here will most likely not work either when using Windows 10/11 as each device will be seen as a network device of it's own.

If this feature is added it's going to be a support headache as is right now.

* Update system rows

* Clean if-else for topbar icons

---------

Co-authored-by: duckaxe <>
@mutatrum
Copy link
Collaborator Author

This PR is going to cause problems for some.

I've tried to get this to work with more than one Bitaxe device connected to the PC (Windows 10) via a USB cable for each and failed to get it to work with ICS or via a bridge within Windows 10, Ethernet 2 and the Network Bridge have a status of "Network cable unplugged" when bridging the two Bitaxe network devices (Ethernet 2 & Ethernet 3) to create a virtual network, it fails, so not able to use ICS that way either.

ICS will work with one device but not two or more.

Using a USB hub here will most likely not work either when using Windows 10/11 as each device will be seen as a network device of it's own.

If this feature is added it's going to be a support headache as is right now.

Windows 10 is not an ideal host pc. I've tested it with 2 on Linux and it works, they are indeed seen as separate internet devices, but that's also what they are. According to the documentation, it should also be possible to have multiple on Windows 10. What I can try is to see if I can add support for RNDIS, next to NCM. RNDIS is the Microsoft version of NCM, so that might play nicer with Windows anyways. TinyUSB supports both.

As for the host machine, as mentioned in the PR, we need to add instructions on how to use a Raspberry Pi as host, in such a way it works on the complete LAN. That's a far more sustainable solution than to hook them onto your desktop or laptop.

Furthermore, it's not a feature for regular Joe. If you really want to go Wi-Fi free, or want to put the devices in a location that has bad coverage, this can be a solution. Maybe it should treated more as the oc flag, behind some sort of toggle. Your point is valid: people seeing the dropdown and just enabling this can cause issues.

Copy link
Collaborator

@duckaxe duckaxe left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FE 👍

@Everade
Copy link

Everade commented Jan 13, 2026

Does this also support a USB-C to Ethernet Adapter rather than hooking it up to a Host PC?

@mutatrum
Copy link
Collaborator Author

Does this also support a USB-C to Ethernet Adapter rather than hooking it up to a Host PC?

No, for several reasons:

  • The USB port on all current Bitaxe models is not powered, it only has data lines. An Ethernet Adapter needs power. Maybe you can work around it with a power injector, but not sure.
  • There are many different models of USB-C to Ethernet adapters, and they might need separate drivers to work.
  • Host mode USB (which is what's needed for this) is less mature on this microcontroller compared to client mode USB (which is what this PR uses).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants