FireFLY Arduino support 0.1.0 — development preview
=================================================
CH32X035F8U6 • 48 MHz • 62 KiB sketch flash • 20 KiB RAM

USB CDC starts automatically, including in an empty sketch. Serial is the USB
serial port. A 1200-baud open/close asks the MCU to restart into the existing WCH
factory USB ISP loader; no replacement bootloader is installed.

STATUS
Compiles on macOS arm64 with Arduino CLI 1.4.1 and WCH toolchain 8.2.0.
The installer and all three examples were checked. USB enumeration, automatic
reset, ROM upload, analog readings and GPIO operation still need a physical
FireFLY board test. Other host platforms have download definitions but have not
been run. Do not treat this preview as a verified production firmware release.

INSTALL
1. Install Arduino IDE 2.x and Python 3. Arduino CLI is bundled with the IDE on
   macOS and Windows. On Linux install Arduino CLI and put it on PATH.
2. Extract this whole ZIP. Open a terminal in the extracted directory and run:
      macOS/Linux: python3 install.py
      Windows:     py -3 install.py
   If CLI detection fails, add --cli "/full/path/to/arduino-cli".
   The installer uses Arduino IDE's saved configuration when present.
   For another CLI configuration, add --config-file /path/to/config.yaml.
3. The installer installs the official WCH:ch32v 1.0.4 compiler dependency,
   copies FireFLY into your configured sketchbook hardware directory, and
   downloads SHA-256-verified wchisp 0.3.0 from its official GitHub release.
   Previous FireFLY installations are preserved in sketchbook/firefly-backups.
4. Restart Arduino IDE. Tools > Board > FireFLY Boards > FireFLY.

FIRST UPLOAD / RECOVERY
1. Tools > Upload mode > USB recovery.
2. Hold the BOOT button while plugging the board into USB; release it.
3. Open examples/USBSerial/USBSerial.ino from this package, then Upload.
   The ROM loader is a USB device, not a serial COM port. In recovery mode
   Arduino does not attempt a serial reset. Only one WCH ISP device should
   be attached: wchisp selects the first compatible device.
4. After the sketch starts, select its FireFLY USB Serial port and choose
   Tools > Upload mode > USB automatic.

On Windows the ROM loader requires a libusb-compatible driver (WinUSB), while
sketch CDC uses the standard USB serial driver. Install the ROM driver only
for 4348:55e0 / 1a86:55e0, not the sketch's serial interface. On Linux USB ISP
may require a udev permission rule; CDC may require dialout group membership.
See wchisp's official platform instructions: https://github.com/ch32-rs/wchisp

NORMAL UPLOADS
Close Serial Monitor before uploading. Click Upload with FireFLY's port selected.
Arduino sends the 1200-baud touch; the firmware schedules a clean USB disconnect,
selects factory boot mode and resets. The upload wrapper waits up to 12 seconds
for ROM enumeration. It retries only the no-device error, never a failed flash.
An interrupted or unresponsive sketch is recoverable with the BOOT procedure.

SERIAL / USB BEHAVIOR
Serial.begin(115200) is supported; the baud value does not change USB speed.
Serial.end() deliberately does not detach USB. USB runs before setup(), between
loop() calls, in delay()/yield(), and during Serial operations. Long tight loops
must call yield(). Disabling interrupts or crashing can prevent USB reset; BOOT
recovery remains available. FireFLY_enterBootloader() schedules a reset directly.
USB D- (PC16) and D+ (PC17) never appear in the Arduino pin list.
The PHY uses WCH's 5 V mode because USB feeds VSYS through the board's diode.

PINS
Arduino name    MCU pin    Purpose
D0              PA3       Bottom pad D0
D1 / A0         PA6       Bottom pad D1; ADC
D2 / A1         PB0       Bottom pad D2; ADC
D3              PB3       Bottom pad D3
D4              PC19      Bottom pad D4; debug function released at startup
TOUCH / A2      PB1       Central underside electrode; raw GPIO/ADC
LED_LEFT        PB11      First onboard addressable LED data
LED_RIGHT       PA4       Second onboard addressable LED data

Touch sensing and the selected addressable LED protocol need separate drivers;
this release exposes their pins but does not claim those drivers are validated.
The onboard LEDs are not ordinary digitalWrite() indicator LEDs. PadBlink uses
an EXTERNAL LED and resistor on D0. No LED_BUILTIN alias is defined.
No complete hardware SPI/I2C bus is exposed by the perimeter pads; those buses
are disabled by default. No UART pins are claimed by default. PA3 is not assigned
an ADC alias because availability differs by chip revision.

VCC is the unregulated VSYS rail, not a 3.3 V output. BAT is battery positive;
GND is shared ground. The board does not charge or protect the battery.
See the hardware guide before wiring external devices.

USB IDENTITY
This preview uses pid.codes' shared development pair 1209:0001, for private
in-house testing only. It must not be used in devices manufactured, redistributed
or sold. Allocate a proper USB identity before distribution. Then update both
firefly_descriptors.c (FIREFLY_USB_VID/PID) and boards.txt port-identification IDs.
https://pid.codes/1209/0001/

COMMAND LINE
FQBN: firefly:ch32:firefly:upload_mode=auto
Recovery: firefly:ch32:firefly:upload_mode=recovery
Example:
  arduino-cli compile --fqbn firefly:ch32:firefly examples/USBSerial
  arduino-cli upload --fqbn firefly:ch32:firefly:upload_mode=auto \
    --port /dev/cu.usbmodemYOURPORT examples/USBSerial

SOURCES AND LICENSES
UPSTREAM.txt records exact source revisions. Original Arduino/WCH license
headers are retained; the WCH SDK is for WCH microcontrollers only. TinyUSB is
MIT licensed. FireFLY-specific glue, installer and upload wrapper are MIT.
The full modified board/core source is included so sketches can be rebuilt.
Toolchain/uploader binaries are downloaded from their upstream projects and
retain their upstream licenses. wchisp v0.3.0 is GPL-2.0; source: https://github.com/ch32-rs/wchisp/tree/v0.3.0
