For the complete documentation index, see llms.txt. This page is also available as Markdown.
Page cover

First custom joystick

This guide will walk you through the steps required to map your joystick axes to RC Link channels.

Step 1: Identify Your Joystick ID and Axes

Before creating configuration files, you need to know which axis IDs correspond to which joystick movements. You can skip that part if you own x56 or winwing F-16 stick.

  1. Insert the SD card into Magic-Box

  2. Connect your joystick

  3. Power on Magic-Box using your LiPo battery

  4. Press the A button to access the menu

  5. Navigate to the Diagnostics option

  6. Select Events from HOTAS from the sub-menu

  7. Write down device ID (something like A-BCD-E)

  8. Move your joystick to identify axis IDs:

    • Move the stick left to right and note the axis ID shown on screen — this will be your roll axis

    • Move the stick up and down and note the axis ID — this will be your pitch axis

  9. Write down these axis IDs — you'll need them for your configuration file

since v1.7.1

Step 2: Back Up the SD Card

Before making any changes to your Magic-Box configuration, you MUST back up the SD card, especially the /magic-box partition. This contains all your configuration files and examples that you'll need as reference.

  1. Shutdown your Magic-Box (Menu -> Shutdown System)

  2. Remove the SD card from the device

  3. Insert the SD card into your computer using a card reader

  4. Make a complete copy of the /magic-box partition to your computer

  5. Pay special attention to the /magic-box/config directory, as it contains valuable example configurations

If anything goes wrong during setup, you can restore this backup and return to a working state.

Step 3: Create Your First Profile

IMPORTANT: Back Up Your SD Card First

With your SD card backed up, it's time to create your first profile:

  1. Navigate to the /magic-box/config/profiles directory

  2. Create a new file named my-profile.yaml (you can name it whatever you prefer)

  3. Add the following content to the file:

This profile configuration tells Magic-Box to use the name "My Test" and load joystick bindings from a file we'll create in the next step.

Step 4: Create Joystick Binding Configuration

Now we need to create the joystick binding file referenced in your profile, using the axis IDs you identified during diagnostics in First custom joystick:

  1. Navigate to /magic-box/config/binding/ on your SD card

    • IMPORTANT: If the directory doesn't exist, create it

  2. In this directory, create a new file named my-joystick.yaml

    • IMPORTANT: This filename must match what you specified in your profile

  3. Add the following configuration, replacing the axis numbers with the ones you identified during your diagnostics session and use proper device-id or device-name-like property

  1. Save the file

This basic configuration maps three essential axes:

  • roll (axis 0): controls left/right movement

  • pitch (axis 1): controls forward/backward movement (and is reversed)

The roll and pitch keys are now ready to be assigned to channels.

Step 4: Create Channel Mapping Configuration

Now you need to create a channel mapping file to define how your joystick axes correspond to RC transmitter channels:

  1. Navigate to /magic-box/config/channels/ on your SD card

    • IMPORTANT: If the directory doesn't exist, create it

  2. In this directory, create a new file named my-channels.yaml

    • IMPORTANT: This filename must match what will be referenced in your profile

  3. Add the following configuration to map your joystick axes to RC channels:

  1. Save the file

Step 5: Testing

  1. Insert SD card into Magic-Box

  2. Power Up Magic-Box:

    • Plug your USB controller (joystick) into Magic-Box

    • Connect your LiPo battery to Magic-Box via the XT60 connector

    • Verify the power LED illuminates

    • Wait to boot OS for 30 seconds

  3. Select Your Profile:

    1. Use the onboard screen and navigation buttons to select your newly created "My Test" profile

    2. The Magic-Box will now load your joystick binding configuration

    3. If you encounter any errors, check your configuration file syntax

    4. Check on Channels screen if channels values change as expected

Next Steps

Once your basic setup is working, you might want to:

  • Connect your Radio to Magic-Box via PPM or SBUS

  • Fine-tune your controls (see Joystick Binding File)

  • Add more devices the same way as the main joystick (throttle or/and rudder)

  • Add a head tracker for enhanced FPV experience

Last updated