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 Advanced Options -> 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 Advanced Options -> 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 Advanced Options -> 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 Advanced Options -> 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 Advanced Options -> 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 Advanced Options -> 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 Advanced Options -> USB screen, configure the USB mode as peripheral or host.
  • Note: USB configuration requires a reboot to take effect.

3. Device Tree Configuration​

3.1 Device Tree File Structure​

  • The basic device tree configurations for the RV1103 / RV1106 chips used in Luckfox Pico, such as rv1106.dtsi and rv1106-pinctrl.dtsi, are provided by Rockchip. These configurations, along with the hardware resources of Luckfox Pico, set the default configuration in the .dtsi file. The model-specific hardware device information is configured in the .dts file.
  • The configurations in the .dts file have the highest priority and can override the settings in the .dtsi file. Nodes in the .dtsi can be referenced to modify attributes or recreate nodes.
  • For convenience, the board-specific .dts file is symlinked to <luckfox-pico SDK>/config/dts_config after running ./build.sh. Normally, only the device functionality configuration in the .dts file needs to be edited, and the .dtsi file should remain unchanged.

3.2 Common Configurations​

3.2.1 GPIO Configuration​

Pins are configured as GPIO by default. The high or low output levels can be set using sysfs, but default pull-up or pull-down configurations must be done through the device tree or by writing to registers. To configure gpio1 pc7 as a pull-up by default, add the following to <luckfox-pico SDK>/config/dts_config:

/{
    /*-------------------------------------------------------*/
    /*----------------------other data-----------------------*/
    /*-------------------------------------------------------*/

    gpio1pc7:gpio1pc7 {
        compatible = "regulator-fixed";
        pinctrl-names = "default";
        pinctrl-0 = <&gpio1_pc7>;
        regulator-name = "gpio1_pc7";
        regulator-always-on;
    };  
};

&pinctrl {
    gpio1-pc7 {
        gpio1_pc7:gpio1-pc7 {
            rockchip,pins = <1 RK_PC7 RK_FUNC_GPIO &pcfg_pull_up>;
        };
    };
};
  • gpio1pc7 represents the newly created node, which must be placed under the existing root node; a new root node cannot be created independently.
  • other data represents the default configuration for Luckfox Pico's model and compatible properties.
  • pcfg_pull_up represents the default pull-up, pcfg_pull_down represents the default pull-down, and pcfg_pull_none represents no pull-up or pull-down.

3.2.2 PWM Configuration​

PWM functionality can only be used by one pin at a time. For example, the pins corresponding to PWM1M0 and PWM1_M1 cannot be used simultaneously. The pin usage is controlled through the pinctrl attribute. To enable PWM1M0, add the following to <Luckfox-pico SDK>/config/dts_config:

&pwm1 {
    status = "okay";
    pinctrl-0 = <&pwm1m0_pins>;
};
  • &pwm1 refers to the node, based on rv1106.dtsi.
  • &pwm1m0_pins refers to the pinctrl node containing the pin and multiplex mode information, based on rv1106-pinctrl.dtsi.
  • Since PWM's frequency and duty cycle can be set using sysfs, the device tree configuration for PWM only enables the feature.

3.2.3 UART Configuration​

UART functionality can only be used by one set of pins at a time. For example, the pin sets for UART1M0 and UART1M1 cannot be used together, and the pins within the set cannot be split. Pin usage is controlled through the pinctrl attribute. To enable UART1M0, add the following to <Luckfox-pico SDK>/config/dts_config:

&uart1 {
    status = "okay";
    pinctrl-0 = <&uart1m0_xfer>;
};
  • &uart1 refers to the node, based on rv1106.dtsi.
  • &uart1m0_xfer refers to the pinctrl node containing pin and multiplex mode information, based on rv1106-pinctrl.dtsi.
  • If flow control is needed, ensure the corresponding UART group has flow control pins, and add the necessary ctsn and rtsn pin information to the pinctrl-0 attribute.

3.2.4 I2C Configuration​

I2C functionality can only be used by one set of pins at a time. For example, I2C0M0 and I2C0M1 cannot be used simultaneously, and the pins within the set cannot be split. Pin usage is controlled through the pinctrl attribute. To enable I2C0M0, add the following to <Luckfox-pico SDK>/config/dts_config:

&i2c0 {
    status = "okay";
    pinctrl-0 = <&i2c0m0_xfer>;
    clock-frequency = <100000>;
};
  • &i2c0 refers to the node, based on rv1106.dtsi.
  • &i2c0m0_xfer refers to the pinctrl node containing pin and multiplex mode information, based on rv1106-pinctrl.dtsi.
  • The clock-frequency attribute sets the I2C clock frequency in Hz. You can adjust this according to actual needs, with the default I2C frequency set to 100000 (100kHz) in standard mode.

3.2.5 SPI Configuration​

SPI functionality can only be used by one set of pins at a time. For example, SPI0M0 and SPI0M1 cannot be used together, and the pins within the set cannot be split. However, not all pins within the same SPI group must be used (e.g., only enabling CLK and MISO). Pin usage is controlled through the pinctrl attribute. If only the CLK and MOSI pins are to be enabled for SPI0M0, add the following to <Luckfox-pico SDK>/config/dts_config:

&spi0 {
    status = "okay";
    pinctrl-0 = <&spi0m0_clk &spi0m0_mosi>;
    spidev@0 {
        status = "okay";
        compatible = "rockchip,spidev";
        spi-max-frequency = <50000000>;
        reg = <0>;
    };
    fbtft@0 {
        status = "disabled";
    };
};

  • &spi0 refers to the node, based on rv1106.dtsi.

  • pinctrl-0 refers to the node in the corresponding Luckfox Pico model's .dtsi file. The distinction from rv1106-pinctrl.dtsi is that the pins are separated for easier configuration.

  • The spi-max-frequency attribute sets the SPI clock frequency in Hz. You can adjust this according to actual needs, with the default SPI frequency set to 50 MHz.

  • spidev@0 refers to a child node in .dtsi used for SPI communication with the main device.

  • fbtft@0 refers to an FB device node in .dtsi, which should not be enabled together with spidev@0. If the fbtft@0 node does not exist in the corresponding .dtsi, this configuration will have no effect.

  • The pinctrl/spi0 node configures the pins spi0m0_clk, spi0m0_mosi, spi0m0_miso, and spi0m0_cs0, but only spi0m0_clk and spi0m0_mosi are used. Unused pins will not be enabled for SPI functionality.

    /* 该 pinctrl 节点的创建已经在 dtsi 实现，在 dts 不需要添加 */
    &pinctrl {
        spi0 {
            spi0m0_clk: spi0m0-clk {
                rockchip,pins = <1 RK_PC1 4 &pcfg_pull_none>;
            };
            spi0m0_mosi: spi0m0-mosi {
                rockchip,pins = <1 RK_PC2 6 &pcfg_pull_none>;
            };
            spi0m0_miso: spi0m0-miso {
                rockchip,pins = <1 RK_PC3 6 &pcfg_pull_none>;
            };
            spi0m0_cs0: spi0m0-cs0 {
                rockchip,pins = <1 RK_PC0 4 &pcfg_pull_none>;
            };
        };
    };

3.2.6 RGB Configuration​

Luckfox Pico Ultra / Ultra W supports driving an RGB interface LCD screen, which requires multiple pins. Ensure that all the required pins are not configured for other functions before enabling the RGB interface. To configure the Luckfox Pico Ultra to drive the LF40-720720-ARK screen, add the following to <Luckfox-pico SDK>/config/dts_config:

&rgb{
    status = "okay";
    pinctrl-0 = <&lcd_pins>;
};

&panel{
    display-timings {
        timing0:timing0 {
            clock-frequency = <30000000>； 
            hactive = <720>;
            vactive = <720>;
            hback-porch = <44>;
            hfront-porch = <46>;
            vback-porch = <18>;
            vfront-porch = <16>;
            hsync-len = <2>;
            vsync-len = <2>;
            hsync-active = <0>;
            vsync-active = <0>;
            de-active = <0>;
            pixelclk-active = <1>;
        };
    };
};

  • &rgb refers to the referenced node, with the default attribute configuration found in the corresponding Luckfox Pico model's .dtsi and rv1106.dtsi. If the RGB interface is not needed, change the status attribute to disabled.
  • &timing0 refers to the timing information of the screen, which should be configured according to the screen's specifications.
  • For more configuration details, refer to the RGB section.

3.2.7 TouchScreen Configuration​

Luckfox Pico Ultra / Luckfox Pico Ultra W support controlling the touchscreen via the I2C interface. A sub-node needs to be added to the I2C3 node to configure the touchscreen. For example, to configure the Luckfox Pico Ultra using I2C3 to drive the GT911 touchscreen chip on the LF40-720720-ARK screen, add the following to <Luckfox-pico SDK>/config/dts_config:

&i2c3 {
    status = "okay";
    pinctrl-0 = <&i2c3m2_xfer &tp_rst &tp_irq>;
    clock-frequency = <100000>;
    GT911:touchscreen {
      compatible = "goodix,gt911";
      reg = <0x14>;

      interrupt-parent = <&gpio0>;
      interrupts = <RK_PA3 IRQ_TYPE_EDGE_FALLING>;

      reset-gpios = <&gpio0 RK_PA4 GPIO_ACTIVE_LOW>;
      pinctrl-names = "default";
    };
};

  • GT911:touchscreen represents the created touchscreen sub-node. The related attribute configurations should be set according to the touchscreen specifications and the matching Goodix driver.

  • pinctrl-0 configures the I2C pins needed for the touchscreen, as well as the reset pin (tp_rst) and touch interrupt pin (tp_irq). The referenced nodes are configured in the corresponding Luckfox Pico model's .dtsi file.

  • reg configures the touchscreen's I2C device address.

  • pinctrl/touchscreen configures the tp_rst and tp_irq pins. Ensure these pins are not reused for other functions or occupied by other drivers.

```c++
/* The pinctrl node creation has already been implemented in the dtsi file, so it is not needed in the dts */
 &pinctrl {
    touchscreen {
        tp_rst:tp-rst {
            rockchip,pins = <0 RK_PA4 RK_FUNC_GPIO &pcfg_pull_up>;
        };
 
        tp_irq:tp-irq {
            rockchip,pins = <0 RK_PA3 RK_FUNC_GPIO &pcfg_pull_none>;
        };
    };    
 };
```
  • For more configuration details, refer to the RGB section.

3.2.8 USB Configuration​

Luckfox Pico's USB is set to peripheral mode by default, allowing the USB to act as a device for ADB terminal access and as an RNDIS device for LAN access on the computer. When in peripheral mode, plugging in devices like a USB flash drive or keyboard will not have any effect. To configure the USB as host mode for recognizing attached peripherals, add the following to <Luckfox-pico SDK>/config/dts_config:

&usbdrd_dwc3 {
    status = "okay";
    dr_mode = "host";
};
  • &usbdrd_dwc3 refers to the node that configures the USB mode. Other dependent USB nodes are enabled by default, with the source and default configuration found in rv1106.dtsi and the corresponding Luckfox Pico model's .dtsi file.
  • The dr_mode attribute configures the USB mode. host represents host mode, and peripheral represents device mode.

3.2.9 CSI Configuration​

Luckfox Pico's CSI is enabled by default. On Luckfox Pico / Mini / Plus / Pro / Max, you can control the CSI camera by simply inserting the CSI camera. On Luckfox Pico Ultra / Ultra W, since I2C4 also brings out other pin groups besides CSI, you need to modify the pinctrl-0 attribute of I2C4 to ensure the CSI interface works properly. To enable the CSI interface on Luckfox Pico Ultra, add the following to <Luckfox-pico SDK>/config/dts_config:

&csi2_dphy_hw {
    status = "okay";
};

&i2c4 {
    status = "okay";
    clock-frequency = <400000>;
    pinctrl-0 = <&i2c4m2_xfer>;
};
  • &csi2_dphy_hw refers to the CSI2 D-PHY node, which is the underlying node for the CSI interface. If this node is not enabled, the property settings of other nodes will be ineffective.
  • &i2c4 refers to the I2C4 node. The sub-nodes related to the sensor are enabled in the corresponding .dtsi file, with support for the SC3336 sensor enabled by default.
  • pinctrl-0 is configured by default as “<&i2c4m0_xfer &i2c4m1_xfer &i2c4m2_xfer>” on Luckfox Pico Ultra to ensure complete device tree information in the final compiled DTB. This configuration in the .dts file will override the configuration in the .dtsi file to ensure the CSI is enabled correctly.

3.2.10 SDMMC Configuration​

Luckfox Pico / Mini / Plus / Pro / Max have TF card slots with SDMMC enabled by default. If the system uses an SD card as the storage medium, disabling SDMMC could prevent the system from booting. Only Luckfox Pico Plus has the SDMMC pins exposed, and when Luckfox Pico Plus uses SPI-NAND as the storage medium, SDMMC can be disabled and the pins can be repurposed for other functions. The SDMMC configuration is already added by default in <Luckfox-pico SDK>/config/dts_config:

&sdmmc {
    max-frequency = <50000000>;
    no-sdio;
    no-mmc;
    bus-width = <4>;
    cap-mmc-highspeed;
    cap-sd-highspeed;
    disable-wp;
    pinctrl-names = "default";
    pinctrl-0 = <&sdmmc0_clk &sdmmc0_cmd &sdmmc0_det &sdmmc0_bus4>;
    status = "okay";
};
  • To disable SDMMC, simply change the status attribute to disabled.