GEVINO-TFT-7-10: Skill for Claude Code

GEVINO TFT firmware

You are writing firmware for the GEVINO TFT — an Arduino Zero compatible HMI PLC with a 7" or 10" capacitive-touch TFT (1024×600, Raio RA8876 controller) based on the Microchip SAMD21 (ARM Cortex-M0+, 48 MHz, 256 KB flash, 32 KB RAM), made by GEVA Elettronica. Build in the Arduino IDE / arduino-cli with the Arduino SAMD core, board Arduino Zero (Native USB Port); it also works with Cursor and OpenPLC.

7" vs 10": same board, only the glass changes. Touch controller: 7" = FT5206 (I²C 0x38), 10" = GT9271 (I²C 0x5D). The library drives both and auto-detects the panel — never write touch code by hand, call gevino_touch_setup() once and the same sketch runs on either model.

Read these first

• AGENTS.md — the full programming guide (this skill is its short form).
• src/gevino_tft_io.h — board I/O macros, ADC helpers, Timer.
• src/gevino_tft_touch.h — the 7"/10" touch API.
• src/gevinoTFT_RA8876.h — the RA8876 display driver (tft object).

Non-negotiable rules

1. Respect the include order:

   #include "gevino_tft_io.h"
   #include "All_76_Pic_65K.h"
   #include "gevino_tft_display.h"
   

2. Include gevino_tft_io.h in exactly ONE translation unit (the main .ino): it instantiates the Serial2/Serial3 SERCOM UARTs, their ISRs and the global I/O registers (OutReg/InReg).
3. Call gevino_io_setup() once in setup(), after Serial2.begin()/Serial3.begin(); do not initialise pins yourself.
4. Use the macros: inputs In0…In11, outputs setOut0…setOut7 / resOut0…resOut7, setLed/resLed, set_Rs485_TxEn/res_Rs485_TxEn.
5. Call updateIO() to push outputs (Out1…Out7) and sample inputs (In4…In11): these go through a 74HC595/74HC165 shift-register chain mirrored in OutReg/InReg. In0…In3 and Out0 are direct GPIO. Write non-blocking, state-based code; avoid delay() in loop().
6. Never assign OutReg. The 74HC595's first stage, Q0, is the RA8876 display reset (active low), so only Q1…Q7 are outputs and Out0 is a CPU pin (D44). Change outputs with setOutN/resOutN, or with writeOutputs(v) (bit 1 = Out1 … bit 7 = Out7) and clearOutputs() — never OutReg = 0; nor OutReg = (1 << n);. The reset now lives in its own variable (TftReset, macros setReset/resReset) and updateIO() merges it in, so bit 0 of OutReg is ignored. It did not use to be: clearing OutReg held the display in reset, the panel went dark and every SPI read of the controller returned 0xFF, hanging the library's timeout-less wait loops forever — identical to a faulty display. If a board goes dark and the controller reads 0xFF, suspect this before the hardware.