stm32samples/F1:F103/AS3935-lightning/Readme.md

AS3935-based Lightning Detector

Overview

This project implements a lightning detection system using two AS3935 Franklin Lightning Sensors interfaced with an STM32F103 microcontroller. The device communicates over USB CDC (virtual serial port) and exposes a text-based command protocol for configuration, monitoring, and data extraction. In the next version it is possible to add RS-232 or RS-485 as an alternative to USB.

Key features:

• Dual AS3935 sensors on single SPI channel.
• On-chip ADC for internal MCU temperature and voltage supply monitoring (more features may be added in the future).
• Persistent configuration storage in internal Flash memory.
• USB CDC interface with automatic detection of lightning events.
• Extensive command set for real-time tuning and status readout.

---

Hardware Connections

Pin	Configuration	Function
PA0	GPIO	INT0 - External interrupt from sensor 0 (pull-down)
PA1	GPIO	INT1 - External interrupt from sensor 1 (pull-down)
PA2	GPIO	CS0 - SPI chip select for sensor 0
PA3	GPIO	CS1 - SPI chip select for sensor 1
PA5	SPI1 SCK	SPI clock
PA6	SPI1 MISO	SPI Master In / Slave Out
PA7	SPI1 MOSI	SPI Master Out / Slave In
PA9	USART1 Tx	(unused in this version)
PA10	USART1 Rx	(unused)
PA15	GPIO	USB D+ pull-up control (1.5 kΩ)
PC13	GPIO	On-board LED (active low)

The two AS3935 sensors share the SPI bus but have separate chip select lines and interrupt pins. If necessary, it can be expanded to include more sensors.

---

USB CDC Communication

The device appears as a virtual COM port when connected to a host computer. Communication parameters (baud rate, parity, etc.) are ignored — the underlying USB bulk transport guarantees reliable delivery.

• Line coding: default sent by host (e.g., 115200 8N1) is accepted but not used.
• Ring buffers: 1024 bytes each for TX and RX.
• Command terminator: every command must end with a newline (\n). The response is also terminated by a newline, except for multi-line outputs (help, dumpconf, SPI).

When the host opens the virtual COM port (DTR asserted), the device becomes ready. If the port is closed, the CDCready flag is cleared and any outgoing data is discarded.

---

Command Protocol

General Syntax

<command> [<channel>] [ = <value> ]

• command — case-sensitive name (exactly as listed, all lowercase).
• channel — numeric index of the sensor (0 or 1). Required for sensor-specific commands; omitted for global commands.
• value — decimal integer, hexadecimal (0x prefix), binary (0b prefix), or a string (for commands like setiface). For the SPI command, the value is a sequence of hex bytes and/or quoted text.
• whitespaces around = and between tokens is ignored.

There are two modes:

1. Getter — if = is absent, the current value is returned:

   command<channel> = <current_value>
   

   No OK response follows.

2. Command — also don't need =, but returns OK or error code.

3. Setter — if = is present, the value after = is assigned. The returned value is text describing error code (OK etc.). A getter-style response is not returned after a successful set; only OK appears.

For channel-dependent commands the response includes the channel number, e.g.:

gain0 = 5

Global commands (no channel) use the same format without a number:

restonstart = 1

Commands that are purely actions (e.g., clearstat, resetdef) only take a channel number and do not accept an = sign. On success they reply OK.

Error Codes

If a command cannot be executed, one of the following error strings is returned instead of OK:

Error String	Meaning
BADCMD	Unknown command
BADPAR	Invalid channel number
BADVAL	Invalid value for the setter (out of range or malformed)
WRONGLEN	Buffer overflow or line too long
CANTRUN	SPI communication failure, sensor not responding, or illegal state
BUSY	SPI or ring buffer busy - retry later
OVERFLOW	Input string exceeded maximum length (256 characters)

Command Reference

All commands are defined in the source file commproto.cpp using macro COMMAND_TABLE.

Sensor Configuration Commands

These commands read or write parameters of a specific AS3935 sensor. They require the channel number as the first argument. For details, please refer to the sensor's technical documentation.

Command	Description	Value Range	Default
displco	Display on IRQ pin: 0=nothing, 1=TRCO, 2=SRCO, 3=LCO	0 - 3	0
gain	Amplifier gain (AFE_GB)	0 - 31	18
lco_fdiv	Antenna LCO frequency divider	0 - 3	0
maskdist	Mask disturbers (1 = mask, 0 = allow)	0 or 1	0
minnumlig	Minimum lightning number (0→1, 1→5, 2→9, 3→16)	0 - 3	0
nflev	Noise floor level	0 - 7	2
srej	Spike rejection	0 - 15	2
tuncap	Tune capacitor setting (n·8 pF)	0 - 15	0
wdthres	Watchdog threshold	0 - 15	2

Syntax examples:

gain 0 = 12          set gain of sensor 0 to 12
gain 1               read gain of sensor 1 → gain1 = 5
displco 0 = 1        configure sensor 0 IRQ pin to output TRCO clock
displco 0            read display mode → displco0 = 1

Sensor Action & Status Commands

These commands do not take a value after =, only a channel number.

Command	Description
clearstat	Clear the lightning statistics (last 15 min)
distance	Read estimated distance to the lightning in km (0-63, 63=out of range)
energy	Read energy of the last lightning (24-bit value)
intcode	Read the last interrupt code: 1=Noise, 4=Disturber, 8=Lightning
iscalib	Check if both RCO and TRCO calibrations are done (returns 1 if done)
resetdef	Reset the sensor to factory default settings
wakeup	Wake up the sensor and run RCO calibration

Examples:

wakeup 0            wake up sensor 0, auto-calibrate → OK
iscalib 0           read calibration status → iscalib0 = 1
energy 0            read energy → energy0 = 123456
distance 1          read distance → distance1 = 12
intcode 0           read interrupt flags → intcode0 = 8
clearstat 0         clear statistics → OK
resetdef 0          reset to defaults → OK

Global (Non-Sensor) Commands

These commands do not require a channel number.

Command	Description
dumpconf	Dump the full current configuration (stored in RAM until saved)
eraseflash	Erase the entire Flash configuration storage
help	Print list of all commands and a repository URL
mcureset	Software reset of the MCU
mcutemp	MCU internal temperature in tenths of °C (e.g., 287 = 28.7℃)
readconf	Read sensor configuration from the chip and update RAM for given channel
restonstart	Restore sensor parameters at start-up (0 or 1)
saveconf	Save the current RAM configuration to Flash
setiface	Get/set the USB interface name string (max 16 characters)
time	Current uptime in milliseconds
vdd	Supply voltage VDD in hundredths of a volt (e.g., 330 = 3.30 V)

Examples:

mcutemp               → mcutemp = 287
vdd                   → vdd = 330
setiface = MyDetector   set interface name to "MyDetector"
setiface              → setiface = MyDetector
restonstart = 1         enable automatic restore at power-up
saveconf                save current configuration to Flash
dumpconf                print all stored and current parameters
readconf 0              read sensor 0 parameters into RAM (for later save)

SPI Low-Level Command

The SPI command allows arbitrary bidirectional SPI transactions to a selected sensor.

Syntax:

SPI <channel> = <hexdata>

<hexdata> is a sequence of bytes expressed as space- or comma-separated hexadecimal numbers (without 0x prefix), optionally with quoted text strings. Anything inside double quotes is transmitted as raw ASCII.

Example:

SPI 0 = 00 01 "hello" 02

This sends the bytes 0x00, 0x01, 'h','e','l','l','o', 0x02 to sensor 0 and returns the received bytes as a hex dump.

Response format:

SPI0 = 
00 01 68 65 6c 6c 6f 02

---

Lightning Interrupts

The main loop continuously monitors the INT pins (PA0, PA1). When a rising edge is detected and the corresponding DISPLCO setting is 0 (not used as clock output), the code reads the interrupt register:

• Disturber and noise events are reported as:

  INTERRUPT0=NOICE,DISTURBER
  

• A lightning event additionally triggers lightning_info(), which prints the energy and distance:

  INTERRUPT0=LIGHTNING
  energy0 = 123456
  distance0 = 12
  

If the pin is configured as a clock output (displco != 0), no interrupt processing occurs. You can mask disturber interrupts by command maskdist n = 0, in this case only NOICE and LIGHTNING will be monitored.

---

Configuration Storage

User settings are stored in the internal Flash of the STM32F103. The Flash area reserved for configuration starts at a fixed address (defined in the linker script) and has a limited capacity. The structure user_conf contains:

• userconf_sz — magic cookie (size of the structure).
• iInterface + iIlength — USB interface name (stored as two bytes per character for Unicode).
• spars[] — per-sensor parameters (gain, WDTH, NF_LEV, SREJ, MIN_NUM_LIG, MASK_DIST, LCO_FDIV, TUN_CAP).
• flags.restore — if 1, all parameters are automatically applied after reset.

Mechanism:

• Each time saveconf is issued, a new copy of the configuration is appended to the Flash storage. A binary search at boot finds the last valid entry.
• If the storage becomes full, the next saveconf will first erase the entire storage and then write the current configuration.
• eraseflash erases the whole configuration area; restonstart controls whether the stored configuration is uploaded to sensors at start-up.

Capacity:

Approximately (FLASH_SIZE * 1024 - offset) / sizeof(user_conf) configurations can be stored. For a typical 64 KB device, this is hundreds of entries.

---

ADC and Internal Sensors

The STM32’s ADC continuously samples the internal temperature sensor (channel 16) and the internal reference voltage (channel 17) in scan mode with DMA circular buffer. A median filter of 9 samples is applied to each channel.

• mcutemp returns temperature in tenths of °C, computed as:

  T = 25 + (V_25 - Vsense)/Avg_Slope, with V_25=1.45 V and Avg_Slope=4.3 mV/°C.

• vdd calculates the supply voltage using the internal 1.2 V reference:

  Vdd = 1.2 * 4096 / (ADC reading of Vrefint).

These commands do not require a sensor channel.

---

Examples

Typical Workflow

1. Connect the device to a USB port and open a terminal at any baud rate.

2. Type help to see the available commands.

3. Wake up the sensors and calibrate:

   wakeup 0
   wakeup 1
   

4. Configure gains, thresholds and other values if need:

   gain 0 = 10
   wdthres 1 = 3
   

5. Verify settings:

   dumpconf
   

6. Enable persistent configuration:

   restonstart = 1
   saveconf
   

7. Monitor lightning events — the device will print INTERRUPT... messages automatically. If need, you can clear statistics periodically or call other setters/getters; for example, reduce the sensitivity or lightning strike threshold during a severe thunderstorm and restore these values ​​after it ends

Reading Sensor Status

Any time you can read sensor status (to get noice information or other data):

intcode 0
energy 0
distance 0

Saving and Restoring Configuration

dumpconf        # see current settings
saveconf        # write to flash
mcureset        # reboot (only if something goes wrong)

After reset, the configuration is automatically loaded (if restonstart was 1).

---

How to distinguish between identical device

The device uses standard USB VID/PID, which are shared for free use by ST. Therefore, it may be difficult to determine which /dev/ttyACMx this particular device corresponds to.

You can set custom interface name (setiface=...). After storing in flash, reconnect or reset device and run lsusb -v for given device. At iInterface field you will see stored name. This field can be used to create human-readable symlinks in /dev.

For automatical creation of symlink in /dev to your /dev/ttyACMx, add this udev-script to /etc/udev/rules.d/99-usbids.rules

ACTION=="add", DRIVERS=="usb", ENV{USB_IDS}="%s{idVendor}:%s{idProduct}"
ACTION=="add", ENV{USB_IDS}=="0483:5740", ATTRS{interface}=="?*", PROGRAM="/bin/bash -c \"ls /dev | grep $attr{interface} | wc -l \"", SYMLINK+="$attr{interface}%c", MODE="0666", GROUP="tty"

---

Build Information

Typing help you will see project repository URL, build number and build date at first string.

The code is distributed under GPLv3.