Skip to main content

Expansion Interface

The Firefly T1 has two 5P-PIN expansion interfaces: one on top and one on the left. The signal pins on these connectors are wired straight to ESP32-S3 GPIOs, plus one 5V output pin (PIN1) that software can switch on and off. The top connector is aimed at driving lighting-type loads, while the left one is aimed at I2C / SPI / UART peripherals.

Two 5-PINs, different jobs

The top connector suits LED strips and high-power dimming; the left connector suits sensors, modules and other bus peripherals.

VCC is yours to switch on

PIN1 is a P-MOS switch driven by GPIO43: high-impedance turns it off, low level turns it on. On battery power you also need pm to enable VCC first.

Signal pins go straight to the MCU

The GPIOs in the middle connect directly to the chip with no extra driver circuitry, and the logic level is 3.3V — never feed a 5V signal into them.

Hardware overview​

The Firefly T1 currently has two expansion interfaces: one 5-PIN interface (top) and another 5-PIN interface (left).

5P-PIN (Top)​

PinFunctionControl port
PIN1VCC output (5V)GPIO43 (high-impedance off, low level on)
PIN2GPIOGPIO14
PIN3GNDDirect GND
PIN4GNDDirect GND (same net as PIN3)
PIN5GPIOGPIO13

Notes:

  • PIN1 is an output port controlled by a P-MOS transistor. It only conducts and outputs VCC when GPIO43 is driven low; keeping it high-impedance turns it off (see "How to turn on the VCC output" below for how to drive GPIO43).
  • PIN3 & PIN4 are connected together as one port, to increase the current-carrying capacity of the contact.
  • PIN2 & PIN5 are GPIO pins directly connected to the MCU, mainly used for outputting control signals.
  • PIN5 (GPIO13) is exactly the data line hard-wired into the ws2812 module — plug an LED strip in here to use WS2812 LED Control (neopixel) directly.

Important:

  • When powered by battery, you must actively turn on "VCC output" through power management (pm) to get 5V output.
  • The display side is the "front". The 5P-PIN order is read "from left to right" on the front.

Firefly T1 5P-PIN expansion interface diagram

5P-PIN (Left)​

PinFunctionControl port
PIN1VCC output (5V)GPIO43 (high-impedance off, low level on)
PIN2GNDDirect GND
PIN3GPIOGPIO42
PIN4GPIOGPIO15
PIN5GPIOGPIO16

Notes:

  • PIN1 is switched exactly like the top connector, by the same GPIO43-controlled P-MOS.
  • PIN3-PIN5 are GPIO pins directly connected to the MCU, mainly used for outputting control signals.

Important:

  • When powered by battery, you must actively turn on "VCC output" through power management (pm) to get 5V output.
  • The display side is the "front". The 5P-PIN order is read "from top to bottom" on the front.

How to turn on the VCC output​

PIN1 on both connectors hangs off the same control line: GPIO43. Both the source code and the official apps do it like this — note that it must be OPEN_DRAIN:

from machine import Pin

vcc_en = Pin(43, Pin.OPEN_DRAIN)
vcc_en.value(1) # high-impedance → P-MOS off, nothing on PIN1
vcc_en.value(0) # gate pulled low → P-MOS on, PIN1 outputs 5V
  • value(1) turns it off: the P-MOS is a high-side switch, and its gate has to be pulled up to the source voltage through an external resistor to switch off reliably — the "high-impedance" state of OPEN_DRAIN is exactly that condition. This is also why VCC is off by default at boot: nobody wants every peripheral powered the instant the device starts.
  • value(0) turns it on: pulling the gate low makes Vgs negative, the P-MOS opens and PIN1 outputs 5V.
  • You must use Pin.OPEN_DRAIN. Driving the gate with the default push-pull output puts 3.3V on it, the P-MOS never fully turns off, and a weak output may remain.
  • On battery power there is one more step: you must first enable "VCC output" through power management (pm), otherwise PIN1 never gets 5V.

What each signal pin can do​

These GPIOs are all ordinary 3.3V digital pins and can be used as GPIO, PWM, or software I2C / SPI / UART:

LocationPinGPIOTypical use
TopPIN214General GPIO / PWM
TopPIN513LED strip data line (hard-wired to the ws2812 module)
LeftPIN342General GPIO / peripheral signal
LeftPIN415General GPIO / peripheral signal
LeftPIN516General GPIO / peripheral signal

One thing to keep in mind: the firmware's shared I2C is already taken (9-Axis Sensor (imu) and power management (pm) use I2C0 with SCL = GPIO1 and SDA = GPIO2). So when you connect your own peripherals, use I2C(1, ...) rather than I2C(0).

Quick start​

Connect a WS2812 strip (top 5-PIN)​

from machine import Pin
import neopixel

vcc_en = Pin(43, Pin.OPEN_DRAIN)
vcc_en.value(0) # turn on the 5V on PIN1 to power the strip

np = neopixel.NeoPixel(Pin(13), 48) # top PIN5 = GPIO13
np[0] = (255, 0, 0)
np.write()

What you should see: the first LED on the strip turns red. To animate the whole strip, the ws2812 module is a better fit — see WS2812 LED Control (neopixel).

Connect an I2C sensor (left 5-PIN)​

from machine import Pin, I2C

vcc_en = Pin(43, Pin.OPEN_DRAIN)
vcc_en.value(0) # power the sensor

i2c = I2C(1, scl=Pin(15), sda=Pin(16), freq=400000) # left PIN4 / PIN5
print(i2c.scan()) # print the addresses found

What you should see: scan() returns a list of addresses (for example [0x68]). If it finds nothing, check the wiring and the power first — SDA / SCL swapped also gives no results.

Common pitfalls​

PitfallCause and correct approach
Peripheral plugged in does nothing at allPIN1 is off by default → run Pin(43, Pin.OPEN_DRAIN).value(0) to turn on the 5V
No 5V on PIN1 when running on batteryOne step is missing: enable "VCC output" through power management (pm) first
Driving GPIO43 with a push-pull outputThe P-MOS never fully turns off → you must use Pin(43, Pin.OPEN_DRAIN)
Pin order counted backwardsThe top connector reads left to right and the left connector top to bottom, both with the display side as the "front"
A 5V module's signal wire wired straight to a GPIOGPIOs are 3.3V and do not tolerate 5V → use a 3.3V version of the module or add level shifting
A high-power load fed straight from PIN1PIN1 is meant to power peripherals; for large currents consider the connector and wire rating and use an external supply when needed
LED strip plugged in but darkMake sure it is on the top PIN5 (GPIO13); and do not forget to turn PIN1 on
Conflict with your own I2C busThe firmware uses I2C0 internally (SCL=1 / SDA=2) → use I2C(1, ...) for your own peripherals

Troubleshooting​

SymptomCause / fix
Peripheral gets no power at allPIN1 is not on; or on battery power VCC was not enabled through pm
PIN1 measures only around 3.3VThe P-MOS is not fully conducting → check that you used OPEN_DRAIN with value(0)
i2c.scan() finds no deviceNo power, SDA/SCL swapped, or you used I2C(0) which the firmware occupies
Strip shows garbage / only the first few LEDs lightData line too long or no common ground; it also shares GPIO13 with the light-painting feature, so only one driver at a time
A GPIO always reads 0The pin was not configured as an input, or another function has taken it → do Pin(n, Pin.IN) before reading
Device reboots as soon as a peripheral is plugged inThe peripheral draws too much current and browns out the supply (PIN1 cannot carry it) → power the peripheral separately and share only ground

Related modules: WS2812 LED Control (neopixel), Power Management (pm) and Five-Way Button (button).

AI usage (coming soon)​

Soon you will not have to look up pins or remember the switching polarity of the P-MOS: describe in plain language what you want to connect and do and the Agent will follow the pin tables in this page to generate a complete program that runs on the Firefly T1.

For example, just tell it:

Connect a WS2812 strip to the top connector, turn on VCC at startup and then run a rainbow effect; connect an I2C temperature and humidity sensor to the left connector and show its reading on the display once a second.

It will combine Pin(43, OPEN_DRAIN), neopixel / ws2812, I2C and the display interface into a working program and place it on the SD card under /sd/apps/.

Agent entry (coming soon)

The entry link will go here. Once it is live, one click takes you straight to describing the app you want.