HID (Human Interface Device) input for MSP_SET_RAW_RC (RC channels)

[stronnag]

Experimental Support for mwp / MSP_SET_RAW_RC and HID devices

Nomenclature

• MSP_SET_RAW_RC MSP message providing RC channel data
• HID Human Interface Device. Typically Joysticks and Game Controllers.

Note: This is experimental. The procedure described below may seem complex (it's not really), it provides steps for validating that the system works and may provide guidance as to how it be improved / integrated into the mwp UI.

Overview

From mwp 25.04.03, mwp is able to receive RC channel data from an HID source and multiplex generated MSP_SET_RAW_RC messages along with other telemetry messages processed by mwp. This enables the model to be controlled by a joystick or game controller connected to the device running mwp (or when running mwp on a Linux based game controller like Steam Deck).

Interface

mwp uses an external UDP HID server (mwp-hid-server). This provides flexibility for third parties to provide an alternative implementation, as well as convenience for experimentation.

• The HID server listens on a defined UDP port (default 31025) for the following commands:

  • raw : Returns 16 int16 values, little endian, representing 16 RC channels.
  • info : Returns information (free form text) on the connected HID device.
  • quit : Terminates the server
  • text : Returns a text string of 16 space separated channel values.
  • set : sets RC data for the first four channels (a testing aid). Data is provided as a set of space separated values, for example set 1600 1700 1010 1889.

mwp's reference implementation has the following options:

$ mwp-hid-server  --help
Usage:
  mwp-hid-server [OPTION?] rc-mapfile

Help Options:
  -h, --help           Show help options

Application Options:
  -v, --verbose        Verbose mode
  -f, --fake           Fake values (for testing without HID hardware)
  -p, --port=31025     Udp port

rc-mapfile is a simple text file that maps the capabilities of the HID device to RC Channels. This is discussed below in the following section.

verbose will display channel values every 10 seconds.

RC Channel Mapping

mwp's reference HID server uses the well known SDL ( Simple DirectMedia Layer) library. This library handles numerous input devices (Joysticks, Game Controllers) in well defined manner across multiple platforms.

mwp provides a tool mwp-hid-test to allow the user to identify the inputs on their HID devices and allocate / map inputs to RC Channels. SDL provides for the following HID inputs:

• Axes : "Sticks" and some switches (3 or more positions).
• Buttons : Some switches (2 position, momentary).
• Hats : ?
• Balls : ?

Note that "Hats" and "Balls" are effectively undefined in the reference server solely because the author has no example of such devices.

mwp-hid-test usage

The user plugs in the required HID controller and starts the application (from a shell / terminal). She can then exercises all the required (stick / switch / button) inputs. mwp-hid-test will record the input, best shown by example:

$ mwp-hid-test
There are 1 joysticks connected.
Entry 0, OpenTX Radiomaster Boxer Joystick guid=0300c19b09120000544f000011010000 game controller=true
Name: OpenTX Radiomaster Boxer Joystick
No. axes 8
No. balls 0
No. buttons 24
No. hats 0
Joystick 0 connected
 ....
Axis 2 value -32608.
 ....
Button 1 released.
 ....
Joystick 0 removed.

The application is started, the device (Boxer radio in HID mode) is detected. If multiple devices are detected, the user will be asked which entry they wish to use.

In the example above:

• The user moved the throttle stick, this is identified as "Axis 2"
• The user moved switch "SF", this is identified as "Button 1".

After exercising all required inputs, the user should prepare a mapping file; this is a simple text file mapping "Axis" and "Button" inputs to RC Channels (RC channels numbered from 1).

$ less boxer.txt
# Sticks
Axis 0 = Channel 1 ; Aileron
Axis 1 = Channel 2 ; Elevator
Axis 2 = Channel 3 ; Throttle
Axis 3 = Channel 4 ; Rudder
# Switches
Axis 4 = Channel 5 ; SE (Arming)
Axis 5 = Channel 6 ; SA
Axis 6 = Channel 7 ; SB
Axis 7 = Channel 8 ; SC
Button 0 = Channel 9 ; SD
Button 1 = Channel 10 ; SF
$

Notes:

• Blank lines, lines starting with # or ; are ignored
• Trailing items after ; or # are ignored (comments / notes).

Definition lines are of the form Axis N = Channel X or Button M = Channel Y.

• The Axis N or Button M data is that shown by mwp-hid-test. The Channel is the RC channel for that input.
• mwp-hid-server maps the value from SDL (-32608 to 32607) to RC range 1000-2000. Buttons are mapped from off = 1000 to on = 2000.
• It is possible to set an input as inverted. This is described in a later post. The same post also describes the use of a deadband.
• Currently the mapping is fixed; if necessary this could be expanded to allow the user to further define the mapping (change ranges, etc.), if that is found necessary.

For Game Controllers, it is (probably) possible to provide a SDL Mapping file as a parameter to mwp-hid-test (for example, see https://github.com/mdqinc/SDL_GameControllerDB), that will (possibly) help the SDL library to manage the device.

$ mwp-hid-test gamecontrollerdb.txt

Usage and Testing

Note: The author has access only to Radiomaster radios in HID mode (no dedicated Joysticks or Game Controllers). While this works for me, it may not yet work for you.

Build development mwp, the HID test tool and server

It may be necessary to first install some additional dependencies:

# Arch / Msys2
sudo pacman -S sdl2-compat readline

# Debian et al
sudo apt install libsdl2-compat-dev libreadline-dev

# FreeBSD
sudo pkg install sdl2 readline

# MacOS
brew install sdl2 readline

Then using your clone of the mwptools repositiory:

cd <mwp dev directory>
git checkout development
git pull
# Build mwp with MSP_SET_RAW_TC / mwp-hid-server support
ninja -C _build install

The HID tools are (post 2025-04-12), installed as part of the build, previously, or for local experiments, they can be built independently:

cd src/samples/hidex
make install

Note this installs to $HOME/.local; if you want to install elsewhere, set prefix (and use sudo as required):

make && sudo make install prefix=/usr

Initial Tests

Standalone

Once you've installed mwp-hid-server, you can test it "standalone' if you wish:

In one terminal:

# rc-mapfile.txt is the RC  mapping file created earlier:
$ mwp-hid-server -v rc-mapfile.txt

Then you can send it some commands:

Note: A later post describes mwp's mwp-hid-cli may be used instead of nc or bash to send commands to exercise mwp-hid-server.

# No device connected ... returning "failsafe" values
$ echo "text" | nc -u localhost 31025 -w 1 ; echo
  897  897  897  897  897  897  897  897  897  897  897  897  897  897  897  897
# No device connected, "fake" mode mwp-hid-server -f ...
$ echo "text" | nc -u localhost 31025 -w 1 ; echo
 1500 1500 1000 1500 1000 1001 1002 1003 1004 1005 1006 1007 1009 1010 1011 1012
$ echo "info" | nc -u localhost 31025 -w 1 ;  echo
No joystick connected
# Connect the Boxer ..
$ echo "info" | nc -u localhost 31025 -w 1 ;  echo
OpenTX Radiomaster Boxer Joystick Axes: 8 Buttons: 24
$ echo "text" | nc -u localhost 31025 -w 1 ;  echo
 1500 1500 1000 1500 1000 1000 1000 1000 1000 1000 1500 1500 1500 1500 1500 1500
# Terminate the server
 echo "quit" | nc -u localhost 31025
 # or
 echo "quit" > /dev/udp/localhost/31025

Ensure mwp-hid-server is closed before trying with mwp.

mwp

mwp currently requires that an environment variable MWP_MSP_RC is set, defining the channel mapping file (and any other mwp-hid-server parameter. In the event that there is a user requirement, this might be replaced by a UI dialog is future.

For now: e.g.

MWP_MSP_RC="/home/user/boxer.txt" mwp

Or persistently set in a shell startup file or ~/.config/mwp/cmdopts.

When mwp starts, it will auomatically invoke mwp-hid-server.

When the main telemetry channel is started, the "stick display" icon will show in the bottom right of the map:

This may be expanded (click on the icon) to show the sticks.

Note:

• Yes, it's a Windows VM
• In the console behind mwp, you can see that the arming status has changed to show that "Throttle" is also now an arming blocker.

Other Considerations

• The hard part of this is arbitrating serial usage between the need to maintain INAV's requirement for MSP_SET_RAW_RC (minimum of 5Hz refesh) and mwp's telemetry requirement (minimum say (also) 5 MSP/sec, though it this is not a hard limit, rather a usability desire).
• You may consider using USE_MSP_RC_OVERRIDE / MSP RC Override and a backup TX.
• Note that mwp tries to send MSP_SET_RAW_RC messages every 150 milliseconds (c. 7Hz). This interval may be configurable in the future. It was chosen to minimise the chances of fail-safe while maintaining a decent telemetry rate.

Serial Usage Metrics

mwp can monitor MSP message rates and automatically log the information. If you are testing this MSP_SET_RAW_RC functionality in mwp, please add the following to ~/.config/mwp/cmdopts / %LOCALAPPDATA%\mwp\cmdopts:

MWP_STATS_LOG=60

This will log MSP throughput every minute into mwp_stderr_YYYY_MM_DD.txt.

• Connect mwp to the FC for at least five minutes.
• Describe your telemetry hardware, the OTA device and any integration device (e.g. a Bluetooth device between a telemetry radio and the GCS)
• Provide usage metrics (the mwp_stderr_YYYY-MM-DD.txt log file).

Example

• Telemetry device: Ebyte E220 LoRa, 115200 ground speed, 38400 air speed, USB connection to GCS.

• mwp_stderr_YYYY-MM-DD.txt file with lines like:

...
12:58:30.571459 Initial cycle 0.680451 (b=400 r=587.8, bi=4702.8) *
...
13:13:30.168812 900.267s, rx 341851b, tx 139948b, (380b/s, 155b/s) to 0 wait 0, avg poll loop 62 ms messages 15046 msg/s 16.7
...
13:14:15.113726 945.195s, rx 358998b, tx 146799b, (380b/s, 155b/s) to 0 wait 0, avg poll loop 62 ms messages 15797 msg/s 16.7

This device appears usable.

Postscript

The author owns no game controllers and a limited range of older telemetry devices, so if this capability is to become production, user involvement in the test and evaluation process is needed.

[stronnag]

And if nc or bash is too hard, there's a simple mwp-hid-cli tool to investigate the hid server. This allows the user to send the server commands listed in the first post to a running mwp-hid-server.

$ mwp-hid-cli
udp conn 127.0.0.1:38668 127.0.0.1:31025
> text
 1500 1500 1000 1500 1000 1001 1002 1003 1004 1005 1006 1007 1009 1010 1011 1012
>

[stronnag]

invert and deadband are now implemented:

mwp-hid-test

You can experiment with suitable deadband values:

$ mwp-hid-test --help
Usage:
  mwp-hid-test [OPTION?]

Help Options:
  -h, --help         Show help options

Application Options:
  -d, --deadband     Deadband (in SDL frame of reference)

note that deadband is applied in terms of the SDL resolution, so 1 microsecond of RC PWM is equivalent to c. 65 SDL units.

mwp-hid-server mapping file

The mapping file supports deadband and invert, for example:

$ less boxer.txt
# Sticks
Axis 0 = Channel 1 ; Aileron
Axis 1 = Channel 2 ; Elevator
Axis 2 = Channel 3 ; Throttle
Axis 3 = Channel 4  invert ; Rudder
# Switches
Axis 4 = Channel 5 ; SE (Arming)
Axis 5 = Channel 6 ; SA
Axis 6 = Channel 7 invert ; SB
Axis 7 = Channel 8 ; SC
Button 0 = Channel 9  invert ; SD
Button 1 = Channel 10 ; SF

deadband = 200

• deadband is a global option and is specified with the deadband key and a value in the range 1-1024.
• invert is a per-channel keyword. Add invert after the the channel number and before and trailing comment.

In the above example, channels 4, 7 and 9 will be inverted.

[arealmess]

Radiomaster Ranger Micro 2.4ghz,115200 air/ground speed, mLRS using MspX, external power, USB-C to steamdeck

mwp_stderr_2025-04-22.txt

Sorry for the long logs lol. I had interference from an onboard pi hotspot at first but caught it
Here's my mapping also. It does need some kind of button programming on the steamdeck side. I was just holding the arm button down
steamdeck.txt

[stronnag]

Having at least 75 sessions without context is not particularly useful, but some general observations:

• The entries with a usefully long transaction length (2000+ messages) settle down to c. 15 msp/second. This is adequate.
• You are using mLRS. As mLRS internally uses MSP_SET_RAW_RC to provide RC Contriol, ground station based MSP_SET_RAW_RC cannot work. The mLRS internal MSP_SET_RAW_RC will overwhelm the GCS due to its much greater update rate. USE_MSP_RC_OVERRIDE / MSP RC Override makes no difference, as the FC cannot distinguish bwteen mLRS generated MSP_SET_RAW_RC and GCS generated MSP_SET_RAW_RC .

There are two ways mwp / MSP_SET_RAW_RC can work:

• A TX that does not implement MSP_SET_RAW_RC (e.g. CRSF, SBus, IBus) is used, the FC is built with USE_MSP_RC_OVERRIDE , MSP RC Override is asserted with appropriate msp_override_channels set; or
• No TX is usedl; the FC RX protocol is set to MSP and mwp's MSP_SET_RAW_RC is the sole provider of RC control. This may be considered "high risk" due to sharing the serial bearer with control and telemetry and the need to multiplex RC control and telemetry resulting in a relatively low RC update for all transparent serial devices known to me (at least).

[stronnag]

In order to smooth development merges etc. it is now necessary to force HID support when building:

meson setup _build --reconfigure -D enable-hid=true
ninja -C _build install