ezCoo managed multiport KVM switch¶
Warning
While we provide this document for your convenience, this is a third-party hardware device in the same path as a PiKVM. Therefore, you may need to experiment (trial and error) to get it to work how you like. In the case of the U3P (hot key version), it may or may not work as expected.
PiKVM + Multiport Switches compatibility
Please note that this switch requires a USB port for control. The following devices can provide this:
- PiKVM V3 & V4 Plus.
- DIY devices based on Raspberry Pi 2, 3 and 4.
The following devices are not compatible:
- PiKVM V4 Mini - it doesn't have a USB host port and cannot control switches, it's a single-host device.
- DIY based on Raspberry Pi Zero 2 W - it doesn't have USB host port too.
The ezCoo managed switch can be controlled by PiKVM to allow it to connect to multiple hosts. A typical scenario is a single PiKVM device which can control and switch between multiple hosts or servers using the ezCoo switch. UI elements can be added to the GPIO dropdown to allow switching between hosts from the PiKVM webpage. The instructions here were tested with the ezCoo SW41HA HDMI 4x1 switch ezCoo EZ-SW41HA-KVMU3L 4x1 switch OR ezCoo EZ-SW41HA-KVMU3P 4x1 switch. Both older USB2.0 and newer USB3.0 variants are supported. The following was testing on a Raspberry Pi 4 but should also work on the Pi 2 and 3. This document was created using the contributions from multiple users in our Discord and the author appreciates their efforts.
Info
While most images of the switch do not show the sides, there is a Micro USB port on the side of the ezCoo switch. This is the management port, which is controlled via COM port on the ezCoo KVM. When plugged into the Raspberry Pi, it appears as /dev/ttyUSB0.
Info
Audio was not tested, it is assumed to be non-functional.
Tip
ezCoo EZ-SW41HA-KVMU3L - includes 4x1m USB 3.0 A Male to A Male. You will need 1 extra USB A Male to USB Micro B to connect from the PiKVM to the ezcoo "F/W CTL - Management" port
Connections¶
EZCOO Wiring example can be found here Scroll down to bottom of page for picture
Please review the item description and manual before deploying.
From a high level, the ezCoo switch uses standard connections to the host machines (USB-A to USB-B and HDMI for USB2 version, USB-A to USB-A for the USB3 version). The Raspberry Pi OTG connector (the one coming from the USB-C port on a Pi 4 via the custom splitter cable or device) should be connected to the USB 3 port on the ezCoo switch. There is an additional USB cable connected to the managed port on the switch.
-
Connect the USB-C cable from the Raspberry Pi OTG port to ezCoo switch USB 3 port on the front or USB 1 port on the back of the switch. Note: If this cable is connected to the keyboard port (USB 2) of the ezCoo switch, the mouse will not be present.
-
Connect the HDMI out from the ezCoo switch to the Raspberry Pi CSI-2 to HDMI input. Other users have reported HDMI encoder USB dongles as working.
-
Connect a USB-A to Micro USB cable from the Raspberry Pi to the management port on the side of the ezCoo switch.
-
Connect host USB and HDMI cables from the ezCoo switch to the machines to be managed per the switch instructions.
-
At this point the KVM switch should be present as a device on the PiKVM. SSH into PiKVM and ensure a device like
/dev/ttyUSB0is present. The following instructions assume this is the KVM switch.
Info
There is a limitation in the underlying PiKVM software related to plugging video cables from a host which is already powered and connected to a monitor to a Raspberry Pi CSI2-HDMI encoder. These limitations apply equally when using the ezCoo KVM switch. If video is not present in PiKVM, try keeping all host machines off and connecting them directly to the ezCoo switch before powering the hosts on.
Adding UI elements to control the KVM switch¶
The UI can be updated to add buttons to switch between KVM inputs and indicators for which input is currently selected. The instructions below will make these available in the PiKVM UI after clicking the "GPIO" menu button in the KVM view.
-
Enable read-write mode on the SD card via
rw -
Edit the file:
nano /etc/kvmd/override.yamland include the following. Note the assumption that the KVM switch is present on/dev/ttyUSB0:kvmd: gpio: drivers: ez: type: ezcoo protocol: 2 device: /dev/ttyUSB0 scheme: ch0_led: driver: ez pin: 0 mode: input ch1_led: driver: ez pin: 1 mode: input ch2_led: driver: ez pin: 2 mode: input ch3_led: driver: ez pin: 3 mode: input ch0_button: driver: ez pin: 0 mode: output switch: false ch1_button: driver: ez pin: 1 mode: output switch: false ch2_button: driver: ez pin: 2 mode: output switch: false ch3_button: driver: ez pin: 3 mode: output switch: false view: table: - ["#Input 1", ch0_led, ch0_button] - ["#Input 2", ch1_led, ch1_button] - ["#Input 3", ch2_led, ch2_button] - ["#Input 4", ch3_led, ch3_button]Editing '#Input X' to '#Something else' will change the table name in the GUI drop down, if you want a different name, name it something else and restart kvmd.
This now only applies to older images, newer images do not have this issue. Make sure to notate the spaces for each line, needs to be a total of 4 spaces added per line (NOT tabs):
For example: parent: 0 spaces (kvmd:) child: 4 spaces (gpio:) sub-child: 8 spaces (drivers:) sub-sub-child: 12 spaces (ez:) -
Return to read-only mode for the sd card via
ro. -
Restart the kvmd service:
systemctl restart kvmd. -
If you are still not getting KB output, issue a
ls -la /dev/tty* | grep USB, if no output change cables (Alot of cables are power only)
Switching between hosts in the UI¶
To switch between hosts, enter the KVM UI and click the "GPIO" menu. You should see 4 inputs, one of which will have a green circle indicating it is currently selected. Click the other inputs to change the selected host.
Additional step for the USB 2.0 version (Old EOL version)¶
Please remove protocol: 2 to the override.yaml under the type: ezcoo at the same level:
kvmd:
gpio:
drivers:
ez:
type: ezcoo
device: /dev/ttyUSB0
Developer info¶
- The official protocol version 1 reference
-
Differences between protocols 1 and 2
=============================================================================================================================== =********************************************************Systems HELP*********************************************************= =-----------------------------------------------------------------------------------------------------------------------------= = System Address = 00 F/W Version : 1.20 = = Azz : All Commands start by Prefix System Address zz, if [01-99] = =-----------------------------------------------------------------------------------------------------------------------------= = EZH : Help = = EZSTA : Show Global System Status = = EZS RST : Reset to Factory Defaults = = EZS ADDR xx : Set System Address to xx {xx=[00~99](00=Single)} = = EZS CAS EN/DIS : Set Cascade Mode Enable/Disable = = EZS OUTx VS INy : Set Output x To Input y{x=[0~2](0=ALL), y=[1~4]} = = EZS IR SYS xx.yy : Set IR Custom Code{xx=[00-FFH],yy=[00-FFH]} = = EZS IR OUTx INy CODE zz : Set IR Data Code{x=[1~2],y=[1~4],zz=[00-FFH]} = = EZG ADDR : Get System Address = = EZG STA : Get System System Status = = EZG CAS : Get Cascade Mode Status = = EZG OUTx VS : Get Output x Video Route{x=[0~2](0=ALL)} = = EZG IR SYS : Get IR Custom Code = = EZG IR OUTx INy CODE : Get IR Data Code{x=[1~2],y=[1~4]} = = EZS OUTx VIDEOy : Set Output VIDEO Mode = = {x=[1~2], y=[1~2](1=BYPASS,2=4K->2K)} = =-----------------------------------------------------------------------------------------------------------------------------= =Input Setup Commands:(Note:input number(x)=HDMI(x),x=1) = = EZS INx EDID y : Set Input x EDID{x=[0~4](0=ALL), y=[0~15]} = = 0:EDID_BYPASS 1:1080P_2CH_HDR 2:1080P_6CH_HDR 3:1080P_8CH_HDR = = 4:1080P_3D_2CH_HDR 5:1080P_3D_6CH_HDR 6:1080P_3D_8CH_HDR = = 7:4K30HZ_3D_2CH_HDR 8:4K30HZ_3D_6CH_HDR 9:4K30HZ_3D_8CH_HDR = = 10:4K60HzY420_3D_2CH_HDR 11:4K60HzY420_3D_6CH_HDR 12:4K60HzY420_3D_8CH_HDR = = 13:4K60HZ_3D_2CH_HDR 14:4K60HZ_3D_6CH_HDR 15:4K60HZ_3D_8CH_HDR = = 16:H4K_DOLBY_VISION_ATMOS = = EZG INx EDID : Get Input x EDID Index{x=[0~4](0=ALL)} = =-----------------------------------------------------------------------------------------------------------------------------= =*****************************************************************************************************************************= ===============================================================================================================================
Simple troubleshooting steps to perform¶
Video Issues:
Hook a monitor to the output and test
Reseat the cables
Change out the cables
Switching issues:
SSH or open a web terminal to your PiKVM
`ls -la /dev/ttyUSB*` - This should give you an output. If not, try a different cable till an output is displayed.