biffobear_as3935

CircuitPython driver library for the AS3935 lightning detector over SPI or I2C buses.

Warning

The AS3935 chip supports I2C but Sparkfun found it unreliable.

  • Author(s): Martin Stephens

Implementation Notes

Hardware:

  • A lightning detector board based on the Franklin AS3935 IC.

Software and Dependencies:

class biffobear_as3935.AS3935(spi, cs_pin, baudrate=1000000, *, interrupt_pin)

Driver for the Franklin AS3935 with a SPI connection.

Parameters

  • spi (busio.SPI) – The SPI bus connected to the chip. Ensure SCK, MOSI, and MISO are connected.

  • cs (Pin) – The pin connected to the chip’s CS/chip select line.

  • baudrate (int) – SPI bus baudrate. Defaults to 1,000,000 . If another baudrate is selected, avoid +/- 500,000 as this may interfere with the chip’s antenna.

  • interrupt_pin (Pin) – The pin connected to the chip’s interrupt line. Note that CircuitPython currently does not support interrupts, but the line is held high for at least one second per event, so it may be polled. Some single board computers, e.g. the Raspberry Pi, do support interrupts.

class biffobear_as3935.AS3935_I2C(i2c, address=micropython.const, *, interrupt_pin)

Driver for the Franklin AS3935 with an I2C connection.

Parameters

  • i2c (busio.I2C) – The I2C bus connected to the chip.

  • address (int) – The I2C address of the chip. Default is self._0X03.

  • interrupt_pin (Pin) – The pin connected to the chip’s interrupt line. Note that CircuitPython currently does not support interrupts, but the line is held high for at least one second per event, so it may be polled. Some single board computers, e.g. the Raspberry Pi, do support interrupts.

class biffobear_as3935.AS3935_Sensor(*, interrupt_pin)

Register handling for the Franklin AS3935 SPI and I2C drivers.

calibrate_clocks()

Recalibrate the internal clocks. The clocks rely on the tuning frequency of the antenna, so adjust that to 500 KHz +/- 3.5 % before calibrating.

clear_stats()

Clear statistics from lightning distance emulation block. This resets the data used to calculate the distance to the storm front.

property distance

Estimated distance to the storm front (km). Returns None if storm front is out of range (> 40 km).

Type

int

property disturber_mask

Disturber mask. If the mask is True, disturber events do not cause interrupts. Default is False.

Type

bool

property energy

The calculated energy of the last lightning strike. This is a dimensionless number.

Type

int

property freq_divisor

Antenna frequency divisor. The antenna resonant frequency is divided by this value whenever it is output as a square wave on the interrupt pin.

Value must be one of 16, 32, 64, or 128. Default is 16.

Type

int

property indoor

Get or set Indoor mode. This must be set to True if the sensor is used indoors. and False if the sensor is used outdoors. Default is True.

Type

bool

property interrupt_set

The state of the interrupt pin. Returns True if the pin is high, False if the pin is low and None if the pin is set to output a clock or antenna frequency. The pin is pulled low again after the interrupt Status register is read. If the the resgister is not read, then the pin is pulled low again as follows: After 1.0 second for a lightning event, after 1.5 seconds for a disturber event. The interrupt pin is held high for the duration of high noise.

Type

bool

property interrupt_status

Status of the interrupt register. These constants are defined as helpers: LIGHTNING, DISTURBER. NOISE, DATA_PURGE.

Note: This register is automatically cleared by the sensor after it is read.

Type

int

property noise_floor_limit

Get or set the noise floor limit threshold in the range 0 - 7 (default is 2). When this threshold is exceeded, an interrupt is issued. Higher values allow operation with higher background noise but decrease sensitivity to lightning strikes.

Type

int

property output_antenna_freq

When True, the antenna resonant frequency is divided by the freq_divisor and output as a square wave on the interrupt pin. Default is False.

Type

bool

property output_srco

When True, output the SRCO clock signal on the interrupt pin. Default is False.

Type

bool

property output_trco

When True, output the TRCO clock signal on the interrupt pin. Default is False.

Type

bool

property power_down

Power status. If True, the unit is powered off although the SPI and I2C buses remain active.

Type

bool

reset()

Reset all the settings to the manufacturer’s defaults.

property spike_threshold

Get or set the spike rejection threshold in the range 0 - 11 (default is 2). Higher values reduce false triggers but decrease sensitivity to lightning strikes.

Type

int

property strike_count_threshold

Lightning strike count threshold. The minimum number of lightning events before the interrupt is triggered. This threshold is reset to the default value of 1 after being triggered.

Threshold may be 1, 5, 9, or 16. Default is 1.

Type

int

property tuning_capacitance

The tuning capacitance for the RLC antenna in pF. This capacitance is added to the antenna to tune it to within 3.5 % of 500 kHz (483 - 517 kHz).

Capacitance must be in the range 0 - 120. Any of these values may be used, however, the capacitance is set in steps of 8 pF, so values less than 120 will be rounded down to the nearest step. Default is 0.

Type

int

property watchdog

Watchdog threshold in the range 0 - 10 (default is 2). Higher thresholds reduce triggers from disturbers but decrease sensitivity to lightning strikes.

Type

int