Open FFBoard Documentation

Open FFBoard is an open-source force feedback (FFB) interface designed to create a highly compatible platform for FFB simulation devices like steering wheels and joysticks. It is primarily optimized for Direct Drive (DD) steering wheels.

Note: This software is experimental and intended for advanced users. Features may contain errors and are subject to change.

Key Resources:

• Hardware Designs: Found in the OpenFFBoard-hardware repository.
• Configuration GUI: Found in the OpenFFBoard-configurator repository.
• Detailed Documentation: Available on the GitHub Wiki and the Doxygen site.

Open FFBoard provides specific subprojects for different hardware targets. Use the following subprojects based on your hardware:

• F411RE: For FFBoard 1.0 hardware.
• F407VG: For FFBoard 1.2 hardware.
• F407VG_DISCO: For third-party development kits, specifically the ST F407 Discovery board.

Each target subproject is designed to reference the main FFBoard firmware located in the parent directory.

The firmware uses a modular, class-based architecture. This allows you to change the entire main class at runtime, effectively changing the USB device type and complete firmware behavior.

To implement your own extensions:

1. Review the FFBoardMain and ExampleMain class files in the UserExtensions folder.
2. Use the provided helper functions for parsing CDC commands and accessing flash memory.
3. Implement custom interfaces for motor drivers, button sources, or encoders if needed.
4. Utilize the unified command system (defined in CommandHandler.h) to set parameters at runtime across different interfaces.

The firmware's behavior is determined by its 'Main Mode' (Main Class). Common modes include:

• FFB Wheel: A USB 1-axis force feedback device with HID FFB support. It supports multiple analog axis inputs and digital buttons.
• FFB Joystick: A USB 2-axis force feedback device.
• EXT FFB Gamepad: A USB 2-axis gamepad device without HID FFB. This is used for simple non-FFB devices or for sending custom FFB data via commands (see Ext FFB mode).
• CAN Remote Analog/Digital: Sends all supported digital and analog inputs as CAN packets to a main FFBoard.
• CAN Interface: A GVRET-compatible CAN interface used for CAN bus debugging.

The F407_DISCO build target is designed for third-party development kits, specifically the official ST F407-Discovery board.

Key Characteristics:

• Pinout Compatibility: The pinout is closely based on the MMOS/OSW pinouts and should match them for the most part.
• USB Vbus Sensing: USB Vbus sense is disabled in this target. This allows the build to work on boards lacking that specific connection, but it also means the system will not detect if the board is being powered externally via USB.

To avoid hardware damage or a non-working device, ensure you flash the firmware build that matches your specific board version and hardware configuration. Always use the .hex file for updates.

Available Builds:

• F407VG: For Official FFBoard 1.2+. Includes all features. Note: Requires a VBUS connection.
• F407VG_DISCO: For third-party development kits (e.g., ST F407 Discovery board). Uses a different pin mapping. No VBUS required. Refer to the Pinouts and peripherals wiki for details.
• F411RE: For FFBoard 1.0. Note: This version only supports TMC drivers.

To use the HID command system examples in Python, install the hidapi library, which is the preferred API for this project.

pip install hidapi

To manage EEPROM memory addresses, do not manually alter eeprom_addresses.c or eeprom_addresses.h. Instead, define your memory layout in a memory_map.csv file and use the generate_memory.py script to automatically generate the source and header files. This script also performs a sanity check to ensure the memory map is valid.

# Workflow:
# 1. Edit memory_map.csv
# 2. Run the script:
python generate_memory.py

The Python examples provide implementations for the HID command system. To use the HID Force Feedback (FFB) examples, you must ensure that the EXT FFB mainclass is enabled on your device.

For a complete list of available commands to send via HID, refer to the project's official commands documentation.

Note: A legacy pywinusb example is also provided in the repository, but it is restricted to Windows environments.

The project uses git submodules. To ensure all necessary components are present in your local environment, run the following commands:

git submodule init
git submodule update

If you accidentally flash the incorrect firmware, you must perform a clean full erase to recover the device.

To do this:

1. Put the board into DFU mode (or use an ST-link).
2. Perform a clean full erase of the microcontroller.

Open FFBoard supports various motor drivers through different communication interfaces. Use the following table to determine compatibility for your setup: