Skip to content

Commit

Permalink
Use physical serial port if present on WSL2 (#2790)
Browse files Browse the repository at this point in the history 
WSL2 doesn't natively support USB devices such as serial ports, so Sming uses runs the python terminal application inside Windows natively using powershell.

However, as discussed in #2789 this prevents software such as [usbipd](https://github.com/dorssel/usbipd-win) from working.

This PR adds an additional check when running inside WSL2 to see if the nominated port, via `COM_PORT`, is actually present. If so, then it runs the python terminal application normally. If the path isn't present then it is assumed to be a Windows port and powershell is invoked as usual.

Because the `TERMINAL` environment variable is cached by Sming this can cause issues. To maintain existing behaviour this variable is still cached but left empty to indicate default behaviour. If `TERMINAL` has been redefined then that will be run instead. This will require `make config-clean` to clear the existing cached value.
  • Loading branch information
@mikee47
mikee47 authored Jun 6, 2024
1 parent 90511f1 commit 307d6db
Show file tree
Hide file tree
Showing 7 changed files with 25 additions and 10 deletions.
2 changes: 1 addition & 1 deletion Sming/Arch/Rp2040/Components/uf2/component.mk
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ DEBUG_VARS += UF2CONV_PY
UF2CONV_PY := $(COMPONENT_PATH)/uf2conv.py


# Invoke uf2conf utility
# Invoke uf2conv utility
# $1 -> Parameters
ifdef WSL_ROOT
Uf2Conv = powershell.exe -Command "$(PYTHON) $(UF2CONV_PY) $(if $V,--verbose) $1"
Expand Down
1 change: 1 addition & 0 deletions Sming/Components/terminal/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ Options
.. envvar:: TERMINAL

Command line to use when running ``make terminal``.
This is normally empty (undefined) which causes the default python terminal application to run.
Redefine if you want to use a different terminal application.

.. envvar:: KILL_TERM
Expand Down
11 changes: 6 additions & 5 deletions Sming/Components/terminal/component.mk
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,6 @@ endif
CACHE_VARS += COM_OPTS KILL_TERM TERMINAL
COM_OPTS ?= --raw --encoding ascii --rts 0 --dtr 0
KILL_TERM ?= pkill -9 -f "$(COM_PORT) $(COM_SPEED_SERIAL)" || exit 0
ifdef WSL_ROOT
TERMINAL ?= powershell.exe -Command "python -m serial.tools.miniterm $(COM_OPTS) $(COM_PORT) $(COM_SPEED_SERIAL)"
else
TERMINAL ?= $(PYTHON) -m serial.tools.miniterm $(COM_OPTS) $(COM_PORT) $(COM_SPEED_SERIAL)
endif


##@Tools
Expand All @@ -33,4 +28,10 @@ kill_term:

.PHONY: terminal
terminal: kill_term ##Open the serial terminal
ifdef TERMINAL
$(TERMINAL)
else ifeq ($(WSL_COMPORT_POWERSHELL),1)
powershell.exe -Command "python -m serial.tools.miniterm $(COM_OPTS) $(COM_PORT) $(COM_SPEED_SERIAL)"
else
$(PYTHON) -m serial.tools.miniterm $(COM_OPTS) $(COM_PORT) $(COM_SPEED_SERIAL)
endif
2 changes: 2 additions & 0 deletions Sming/build.mk
View file
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,8 @@ else ifeq ($(UNAME), Linux)
ifdef WSL_DISTRO_NAME
DEBUG_VARS += WSL_ROOT
WSL_ROOT := //wsl$$/$(WSL_DISTRO_NAME)
# If serial device is available, use it directly, otherwise via powershell
WSL_COMPORT_POWERSHELL = $(if $(wildcard $(COM_PORT)),,1)
endif
else ifeq ($(UNAME), Darwin)
#OS X
Expand Down
4 changes: 2 additions & 2 deletions Sming/component.mk
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,9 +128,9 @@ flash: all kill_term ##Write the boot loader and all defined partition images
$(Q) $(call CheckPartitionChunks,$(FLASH_PARTITION_CHUNKS))
$(call WriteFlash,$(FLASH_BOOT_CHUNKS) $(FLASH_MAP_CHUNK) $(FLASH_PARTITION_CHUNKS))
ifeq ($(ENABLE_GDB), 1)
$(GDB_CMDLINE)
$(MAKE) gdb
else ifneq ($(SMING_ARCH),Host)
$(TERMINAL)
$(MAKE) terminal
endif

.PHONY: mergeflash
Expand Down
2 changes: 1 addition & 1 deletion Sming/project.mk
View file
Original file line number Diff line number Diff line change
Expand Up @@ -589,7 +589,7 @@ TCP_SERIAL_REDIRECT = $(SMING_HOME)/../Tools/tcp_serial_redirect.py $(COM_PORT)
.PHONY: tcp-serial-redirect
tcp-serial-redirect: ##Redirect COM port to TCP port
$(info Starting serial redirector)
ifdef WSL_ROOT
ifeq ($(WSL_COMPORT_POWERSHELL),1)
$(Q) cmd.exe /c start /MIN python3 $(WSL_ROOT)/$(TCP_SERIAL_REDIRECT)
else
$(Q) $(call DetachCommand,$(PYTHON) $(TCP_SERIAL_REDIRECT))
Expand Down
13 changes: 12 additions & 1 deletion docs/source/getting-started/windows/wsl.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,14 +91,25 @@ This will ensure that the build system can run python scripts either in WSL2 or
Flashing devices
----------------

WSL2 does not currently support access to USB serial devices, so the Sming build system runs
WSL2 does not natively support access to USB serial devices, so the Sming build system runs
the appropriate application directly under Windows using ``powershell.exe``.

Therefore, use the normal Windows COM port name rather than the linux ones (such as /dev/ttyUSB0)::

make flash COM_PORT=COM4


Some USB serial adapters are supported by the `usbipd <https://github.com/dorssel/usbipd-win>`__ project.
If so, then devices such as ``/dev/ttyUSB0``, etc. will be present as usual.
If Sming sees that ``COM_PORT`` actually exists when running in WSL2 then the above powershell workaround
will not be used.

.. note::

The :envvar:`TERMINAL` environment variable is cached by Sming so if the terminal isn't running as expected
try ``make config-clean`` to clear the cached value.


Serial debugging
----------------

Expand Down

3 comments on commit 307d6db

@callimero
Copy link

@callimero callimero commented on 307d6db Jun 6, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I think there need to be made changes in Components/esptool/component.mk to have flashing also working.

Sorry if my wild formatted mail may have confused you. This what I needed to do:

# USB serial ports are not available under WSL2,
# but we can use powershell with the regular Windows COM port
# $1 -> Arguments
ifdef TERMINAL
        $(TERMINAL)
else ifeq ($(WSL_COMPORT_POWERSHELL),1)
        ESPTOOL_EXECUTE = powershell.exe -Command "$(ESPTOOL_CMDLINE) $1"
else
        ESPTOOL_EXECUTE = $(ESPTOOL_CMDLINE) $1
endif

I havn't tested debugging or working with vscode so far, which may also be affected?

Carsten

@mikee47
Copy link
Contributor Author

@mikee47 mikee47 commented on 307d6db Jun 6, 2024

Choose a reason for hiding this comment

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

Thanks. It should be a one-line change I think:

#
# USB serial ports are not available under WSL2,
# but we can use powershell with the regular Windows COM port
# $1 -> Arguments
ifeq ($(WSL_COMPORT_POWERSHELL),1)
ESPTOOL_EXECUTE = powershell.exe -Command "$(ESPTOOL_CMDLINE) $1"
else
ESPTOOL_EXECUTE = $(ESPTOOL_CMDLINE) $1
endif

@mikee47
Copy link
Contributor Author

@mikee47 mikee47 commented on 307d6db Jun 6, 2024

Choose a reason for hiding this comment

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

vscode uses the same build targets so should behave itself :-)

Please sign in to comment.