Skip to main content

luckfox-config Configuration

Luckfox Pico pins have multiple multiplexing functions. Depending on the needs of the actual project, adjustments to the device tree are often required. This section introduces two methods for configuring Luckfox Pico pin multiplexing during the compilation and system runtime stages, allowing flexible configuration of Luckfox-Pico pin interface functions.

1. Introduction​

The Device Tree is a method used in the Linux kernel to describe board-level information about hardware devices. Device Tree files usually have .dts or .dtsi extensions, where .dts files describe specific hardware device information, and the .dtsi files included in .dts files usually describe common information for similar hardware devices. Luckfox Pico device tree files are located in the <luckfox-pico SDK>/sysdrv/source/kernel/arch/arm/boot/dts directory.

During the compilation process, the device tree combines .dts and .dtsi files to compile into a binary dtb file. When the Luckfox Pico system runs, uboot loads the dtb file into memory. During the kernel startup process, the dtb file is parsed, and devices are initialized based on the device tree information, corresponding drivers are loaded, and device control nodes are registered. The kernel reads the dtb not just once. Since Linux 4.4, a mechanism called Dynamic Device Tree has been introduced, allowing configuration information to be overwritten on the loaded dtb at runtime. The kernel drivers adjust based on the new configuration.

Device tree information can be configured during both the compilation and system runtime stages.

1.1 Device Tree Configuration Overview​

The first step in compiling the Luckfox Pico image is to select the corresponding board support files.

./build.sh lunch

  • The board support file information is linked to <luckfox-pico SDK>/.BoardConfig.mk

  • The board support files configure the .dts files corresponding to Luckfox Pico models. Models with common hardware design parts use the same .dtsi files for unified management.

  • The .dts and .dtsi device tree files for different models are as follows:

    Model.dts.dtsi
    Luckfox Picorv1103g-luckfox-pico.dtsrv1103-luckfox-pico-ipc.dtsi
    Luckfox Pico mini arv1103g-luckfox-pico-mini-a.dtsrv1103-luckfox-pico-ipc.dtsi
    Luckfox Pico mini brv1103g-luckfox-pico-mini-b.dtsrv1103-luckfox-pico-ipc.dtsi
    Luckfox Pico plusrv1103g-luckfox-pico-plus.dtsrv1103-luckfox-pico-ipc.dtsi
    Luckfox Pico pro/maxrv1106g-luckfox-pico-pro-max.dtsrv1106-luckfox-pico-pro-max-ipc.dtsi
    Luckfox Pico ultrarv1106g-luckfox-pico-ultra.dtsrv1106-luckfox-pico-ultra-ipc.dtsi
    Luckfox Pico ultra Wrv1106g-luckfox-pico-ultra-w.dtsrv1106-luckfox-pico-ultra-ipc.dtsi

1.2 luckfox-config Overview​

luckfox-config is a tool in the Luckfox Pico root file system that allows for quick configuration of device functions on Luckfox Pico. By using the dynamic device tree mechanism and the fdt tool, most device configurations can be completed without recompiling the dtb.

  • Terminal Support

    System TypeBuildrootUbuntu
    Serial PortSupportedSupported
    SSHSupportedSupported
    ADBThe arrow keys on the keyboard are not functioning.Supported

  • Functionality

    System TypeBuildrootUbuntu
    GPIOSupportedDefault pull-up/pull-down mode not supported
    PWMSupportedSupported
    UARTSupportedSupported
    I2CSupportedSupported
    SPISupportedSupported
    FBTFTSupported only on Luckfox Pico / Plus / Pro / MaxSupported only on Luckfox Pico / Plus / Pro / Max
    RGBSupported only on Luckfox Pico Ultra / Ultra WSupported only on Luckfox Pico Ultra / Ultra W
    TouchScreenSupported only on Luckfox Pico Ultra / Ultra WSupported only on Luckfox Pico Ultra / Ultra W
    USBSupportedSupported
    CSISupportedSupported

2. luckfox-config Configuration​

Note: The configuration of luckfox-config is based on the default device tree file. If the device tree has been adjusted during image compilation, some functions may not work properly.

2.1 Structure​

  • luckfox-config dynamic device tree configuration tool, can perform graphical interactive configuration
  • /etc/luckfox.cfg stores configuration information, which users can edit. The configuration items are loaded each time the root filesystem starts
  • luckfox-config Pin diagram is used to temporarily store key information about the system configuration, allowing users to intuitively understand the current pin configuration status.

2.2 Basic Usage​

  1. Open the graphical configuration interface:

    luckfox-config

  2. Use the ↑ and ↓ keys to select menu items, the enter key to enter, and the ←, → keys or Tab to select the OK and cancel buttons. Use the Esc key to cancel and return, and the space bar to select an option. Any changes will take effect after restarting. Note: When logging in via ADB, you cannot use the direction keys or Tab. Instead, use numbers to select options and enter to confirm.

  3. View the configuration status. When a pin is enabled, it will be marked with an "*" and locked. If the newly enabled interface contains locked pins, it cannot proceed. You can view the current pin lock status in the about menu of luckfox-config or by using the following command:

    luckfox-config show

    • If the pin reuse function is not specified in the pin diagram, the corresponding GPIO will be directly marked.

      In the Luckfox Pico Ultra series, since I2C4 and the CSI camera share pins, the CSI interface is enabled by default, and the pinctrl-0 configuration includes the I2C4 pins, so all I2C4 and RGB pins are marked at the first boot.

  4. Save the configuration

    Common pin reuse configurations (e.g., PWM, UART, I2C, SPI) take effect immediately. Devices whose drivers do not support dynamic detection (e.g., FBTFT, RGB, touch screen, CSI) need a reboot to take effect.

    Note: Settings that need a reboot to take effect are made by directly modifying the dtb. The ENABLE status in luckfox.cfg is only for record. Simply modifying luckfox.cfg does not take effect during configuration loading.

  5. Load the configuration:

    luckfox-config load

    Note: Configuration loading is automatically executed during the root filesystem startup phase. A dtboverlay node is created and the configuration is written according to the /etc/luckfox.cfg file. Normally, this command does not need to be executed manually.

2.3 Common Configurations​

2.3.1 PWM Configuration​

  1. Enter the Compatible Devices -> PWM interface, and luckfox-config will display all supported PWM configurations.

  2. Select the desired option, choose enable to enable, and disable to disable. To cancel the configuration, use the direction keys to select Cancel and return to the previous interface.

  3. If the pin is already reused for another function and marked, selecting enable will display a prompt. The conflicting configuration needs to be disabled for successful enabling.

2.3.2 UART Configuration​

  1. Enter the Compatible Devices -> UART interface, and luckfox-config will display all supported UART configurations.

  2. Select the desired option, choose enable to enable, and disable to disable. To cancel the configuration, use the direction keys to select Cancel and return to the previous interface.

  3. If the pin to be configured is reused for another function and marked, selecting enable will display a prompt. The conflicting configuration needs to be disabled for successful enabling.

2.3.3 I2C Configuration​

  1. Enter the Compatible Devices -> I2C interface, and luckfox-config will display all supported I2C configurations.

  2. Select the desired option, choose enable to enable, and disable to disable. To cancel the configuration, use the direction keys to select Cancel and return to the previous interface. Selecting enable will enter the speed configuration interface.

  3. In the Luckfox Pico Ultra system, enabling CSI will prevent the configuration of I2C4, and enabling the touch screen will prevent the configuration of I2C3.

  4. If the pin to be configured is reused for another function and marked, selecting enable will display a prompt. The conflicting configuration needs to be disabled for successful enabling.

  5. When the touch screen is enabled, I2C3 cannot be configured. When CSI is enabled, I2C4 cannot be configured.

2.3.4 SPI Configuration​

  1. Enter the Compatible Devices -> SPI interface, and luckfox-config will display all supported SPI configurations.

  2. Select the desired option, choose enable to enable, and disable to disable. To cancel the configuration, use the direction keys to select Cancel and return to the previous interface.


  3. If the pin to be configured is reused for another function and marked, selecting enable will display a prompt. The conflicting configuration needs to be disabled for successful enabling.

2.3.5 RGB Configuration​

Note: Currently, only Luckfox Pico Ultra / Ultra W supports touchscreen configuration, and the RGB configuration requires a reboot to take effect.

  1. Navigate to Compatible Devices -> RGB screen, select enable to enter the RGB configuration screen, and fill in according to the product specification of the screen.

  2. Pressing enter will proceed to the next configuration screen. After filling in, press enter again to complete the configuration.

  3. If there are non-compliant configuration items, there will be a prompt.

  4. If the pins to be configured are multiplexed for other functions and marked, selecting enable will display a prompt message. You need to disable the conflicting configuration to successfully enable RGB.

2.3.6 TouchScreen Configuration​

Note: Currently, only Luckfox Pico Ultra / Ultra W supports touchscreen configuration, and it only supports the GT911 touch chip. The touchscreen configuration requires a reboot to take effect.

  1. Navigate to Compatible Devices -> TouchScreen screen, select enable to enter the touchscreen I2C address configuration screen, and select according to the actual situation, usually selecting the 0x14 item.

  2. Navigate to Compatible Devices -> TouchScreen screen, select enable to enter the touchscreen I2C address configuration screen, and select according to the actual situation, usually selecting the 0x14 item.

  3. If the pins to be configured are multiplexed for other functions and marked, selecting enable will display a prompt message. You need to disable the conflicting configuration to successfully enable the touchscreen.

2.3.7 CSI Configuration​

  1. Navigate to Compatible Devices -> CSI screen, select enable to enable and select disable to disable.

  2. It is recommended to configure CSI once after booting the Luckfox Pico Ultra series to prevent affecting subsequent configurations.

  3. If other I2C4 pins are used, CSI cannot be configured to prevent enabling and disabling CSI from affecting ongoing I2C4 tasks.

    • Note: CSI configuration requires a reboot to take effect.

2.4.8 USB Configuration​

  1. Navigate to Compatible Devices -> USB screen, configure the USB mode as peripheral or host.
  • Note: USB configuration requires a reboot to take effect.