Fusion Hat

Fusion Hat Python library for Raspberry Pi.

Quick Links:

• Fusion Hat
  • About Fusion Hat
  • Installation
  • CLI Commands
  • Create docs
  • Debug record
  • About SunFounder
  • Contact us

About Fusion Hat

Fusion HAT is a multifunctional expansion board that allows Raspberry Pi to be quickly turned into a robot. An MCU is on board to extend the PWM output and ADC input for the Raspberry Pi, as well as a motor driver chip. I2S audio module and mono speaker. As well as the GPIOs that lead out of the Raspberry Pi itself.

Installation

Install Fusion Hat

curl -sSL https://raw.githubusercontent.com/sunfounder/sunfounder-installer-scripts/main/install-fusion-hat.sh | sudo bash

After installation, reboot when prompted. After reboot, test the speaker:

fusion_hat speaker test

Tab completion is enabled automatically (open a new shell).

CLI Commands

fusion_hat speaker enable       # Enable speaker
fusion_hat speaker disable      # Disable speaker
fusion_hat speaker test         # Test speaker with a sound
fusion_hat speaker setup        # Run audio setup (--skip-test to skip speaker test)
fusion_hat info                 # Show device info
fusion_hat doctor               # Run hardware health checks
fusion_hat doctor --fix         # Auto-repair driver issues
fusion_hat update_eeprom        # Reflash HAT EEPROM
fusion_hat update_eeprom --erase # Erase then flash EEPROM
fusion_hat version              # Print library version
fusion_hat update               # Self-update from git
fusion_hat scan_i2c             # Scan I2C bus
fusion_hat force_dt_overlay     # Force device-tree overlay
fusion_hat remove_dt_overlay    # Remove device-tree overlay
fusion_hat uninstall            # Uninstall driver and library

Deprecated: Old speaker commands (enable_speaker, disable_speaker, test_speaker, setup_speaker) still work but will be removed in a future version. Use speaker <action> instead.

Create docs

API reference is auto generated by Sphinx. But you need to create rst file manually.

cd docs
sphinx-apidoc -f -d 1 -e -M -P -T -o source/api ../fusion_hat

• -f Force to overwrite existing files.
• -d 1 Set the maximum depth of the module documentation.
• -e put documentation for each module on its own page.
• -M put module documentation before submodule documentation.
• -P include "_private" modules.
• -T don't create a table of contents file.
• -o source/api Specify the output directory for the generated rst files.
• ../fusion_hat Specify the path to the fusion_hat package.

Debug record

sudo pip uninstall --break fusion_hat -y && sudo pip install --break git+https://github.com/sunfounder/fusion-hat.git@1.1.x
sudo pip uninstall --break fusion_hat -y && sudo pip install ~/fusion-hat/ --break-system-packages --no-deps --no-build-isolation
sudo pip install ~/fusion-hat/ --break-system-packages --no-deps --no-build-isolation
cd ~/fusion-hat/driver && make all && sudo make install
cd ~/fusion-hat/examples

CLI Commands

After installing the library, use the fusion_hat command:

fusion_hat <command>

Command	Description
info	Show device info, library/driver/firmware versions, battery, button, LED, and speaker state.
doctor	Run driver and hardware health checks: EEPROM, module file, module load, sysfs, I2C MCU (0x17), DKMS.
doctor --fix	Run health checks and auto-repair issues (e.g. load the kernel module if not loaded, or build and install the driver).
version	Print the library version.
scan_i2c	Scan the I2C bus and list detected device addresses.
enable_speaker	Enable the onboard speaker.
disable_speaker	Disable the onboard speaker.
test_speaker	Enable speaker, play a test tone, then disable speaker.
update_eeprom	Download and reflash the HAT EEPROM. Guides through hardware steps (shorting write-protect pins).
update_eeprom --erase	Erase EEPROM only (write blank 0xFF). Use before update_eeprom to test a blank-to-flash cycle.
setup_speaker	Configure audio (ALSA/PulseAudio). Run after reboot to enable the speaker. Use --skip-test to skip the speaker test.

Example output:

$ fusion_hat doctor

==================================================
  Fusion Hat Driver Status
==================================================

  ✓ EEPROM detection
  ✓ Module file
  ✓ Module loaded
  ✓ sysfs interface
  ✓ I2C MCU (0x17)
  ✓ DKMS            : fusion_hat/1.0.2, 6.12.47+rpt-rpi-2712, aarch64: installed

==================================================

$ fusion_hat info

==================================================
  Fusion Hat Device Info
==================================================

                Name: Fusion Hat
                  ID: fusion_hat
                UUID: 9daeea78-0000-0774-000a-582369ac3e02
          Product ID: 1908
         Product Ver: 10
              Vendor: SunFounder
     Library Version: 1.3.1
    Firmware Version: 1.0.2
      Driver Version: 1.0.2
   User Button State: Released
       Speaker State: Disabled
      User LED State: Off
       Battery level: 83%
     Battery voltage: 8.06 V
    Battery charging: No

==================================================

About SunFounder

SunFounder is a technology company focused on Raspberry Pi and Arduino open source community development. Committed to the promotion of open source culture, we strives to bring the fun of electronics making to people all around the world and enable everyone to be a maker. Our products include learning kits, development boards, robots, sensor modules and development tools. In addition to high quality products, SunFounder also offers video tutorials to help you make your own project. If you have interest in open source or making something cool, welcome to join us!

---

Contact us

website: www.sunfounder.com

E-mail: service@sunfounder.com, support@sunfounder.com