GEVINO-Opto-PNP: Instructions file for Codex

AGENTS.md — Programming guide for the GEVINO Opto PNP

This file is written for LLMs and AI coding agents (Claude Code, Cursor, Copilot, etc.) that write firmware for the GEVINO Opto PNP PLC. It is also useful to human developers. If you are generating Arduino/C++ code for this board, follow these rules.

What the board is

GEVINO Opto PNP is an Arduino Zero compatible industrial PLC based on the Microchip SAMD21 (32-bit ARM Cortex-M0+, 48 MHz, 256 KB flash, 32 KB RAM). It has 11 opto-isolated inputs, 4 short-circuit-protected PNP outputs, 2 analog inputs, an RS485 bus, an SD card slot and optional Ethernet / Wi-Fi / Bluetooth / RTC / cellular modules. Program it with the Arduino IDE using the Arduino SAMD core, selecting Arduino Zero (Native USB Port).

The complete pin map and specifications are in README.md and in the single library header src/gevino_opto_pnp_io.h.

Golden rules

1. Write non-blocking, state-based code. Prefer switch/case state machines. Never block the loop() with delay() in production logic.
2. Include only one header: #include "gevino_opto_pnp_io.h". It bundles the I/O definitions, the SAMD21 ADC helpers and the Timer class — there are no other library dependencies.
3. Do not initialise the I/O yourself. gevino_io_setup() already configures every pin, the drive strength, the LEDs, RS485 and the Ethernet reset. Just call it once in setup().
4. Read inputs and drive outputs with the macros from gevino_opto_pnp_io.h (In1, setOut1, resOut1, …). Do not hard-code raw pin numbers.

Minimal sketch skeleton

#include "gevino_opto_pnp_io.h"

void setup() {
  SerialUSB.begin(115200);   // USB-C debug console
  Serial.begin(115200);      // Bluetooth SPP-C or Wi-Fi ESP8266 module
  Serial1.begin(115200);     // RS485 bus
  gevino_io_setup();         // configures ALL the board I/O
}

void loop() {
  // non-blocking, state-based logic here
}