This is version 2 of the AS3935 project. I’m a lot happier with the way this version behaves.
It uses some different software components than version 1. You shouldn’t need to rebuild your Pi if you’ve started setting up with version 1. The v1 components won’t interfere with the v2 components, although I would advise that you rename your existing ‘Sensors’ directory and start afresh with a new, empty directory.
This is a current in-progress project. I’m using an ams AS3935 lightning detection sensor IC with a Raspberry Pi to detect lightning strikes within approx 40km. To quote from the manufacturer about the AS3935…
AS3935 Franklin Lightning Sensorâ„¢ IC is a programmable fully integrated lightning sensor that detects the presence and approach of potentially hazardous lightning activity in the vicinity and provides an estimation on the distance to the head of the storm. The embedded lightning algorithm checks the incoming signal pattern to reject the potential man-made disturbers. The AS3935 can also provide information on the noise level and inform the external unit (e.g. microcontroller) in case of high noise conditions, with the noise floor generator and noise floor evaluation blocks.
[ul] [li]Lightning sensor warns of lightning storm activity within a radius of 40km[/li] [li]Distance estimation to the head of the storm down to 1km in 14 steps[/li] [li]Detects both cloud-to-ground and intra-cloud (cloud-to-cloud) flashes[/li] [li]Embedded man-made disturber rejection algorithm[/li] [li]Programmable detection levels enable threshold setting for optimal controls[/li] [li]SPI and I²C interface is used for control and register reading[/li] [li]Antenna Tuning to compensate variations of the external components[/li] [li]Supply voltage range: 2.4V to 5.5V[/li] [li]Power-down, listening, and active mode[/li] [li]Package: 16LD MLPQ (4x4mm)[/li] [/ul]
The project is currently using module parts, which means that in it’s simplest form it’s more or less plug-and-play. That does mean it’s probably more expensive too. However, if you have the skills you can build it from individual parts which should be cheaper. I have received a non-Mikroe board that doesn’t need the Pi 3 Click Shield and will test it soon. If you can solder (7 wires) to a small-ish board then you should be able to save some money by using the second approach. I’ll document it when I’ve tested it. Here’s what you need for the project as it stands…
Hardware
- 1*Raspberry Pi - I’m using a 4GB Model 4B, but I think this should also work on Model 3 devices with less RAM and possibly Model 2’s too. The GPIO interface on Model 1’s isn’t compatible though. Raspberry Pi’s are available from many sources and I’m treating it as a commodity device so I won’t discuss it too much within the project. My Pi has the ‘Full’ version of Raspberry Pi OS installed using the Pi Imager tool which is downloadable from the Raspberry Pi site. These instructions assume that your Pi is already built, with the OS installed, is set up to work on your network, that you’re able to log into it and that it’s updated with the latest Pi OS and standard software.
- 1*Mikroe Pi 3 Click Shield - This is an addon board designed to plug into the 40-pin GPIO connector on a Raspberry Pi. It provides two mikroBUS sockets which allow you to plug a wide variety of ‘click boards’ into the Pi. This is a simple way to add sensors onto a Pi, but be aware that Pi software isn’t available for all of the sensor boards so you may have to write your own/adapt other code. You can buy the Pi 3 Click Shield direct from Mikroe Pi 3 Click Shield in the US, and also some electronics suppliers in other countries, e.g. RS Components or Farnell in the UK. Note that whilst this is called a ‘Pi 3’ shield it is also compatible with the Pi 4 (and I think the Pi 2).
- 1*Mikroe Thunder Click board - This is a mikroBUS module that plugs into the Pi 3 Click Shield. It has an AS3935 lightning detector chip and a MA5532 coil antenna built onto the module with supporting components. You can buy the Thunder Click direct from Mikroe Thunder Click in the US, and also some electronics suppliers in other countries, e.g. RS Components or Farnell in the UK.
Assembly
- Plug the Pi 3 Click Shield onto the 40-pin GPIO connector on the Pi. Follow the Click Shield instructions for how to do this. Note: Make sure your Pi is turned off when you do this!
- Plug the Thunder Click board into one of the sockets on the Click Shield. It will work in either socket. Mine is plugged into socket 2 because I have another module plugged into socket 1 (see another project to be documented later on). Ensure the the small GPIO/ADC switch on the Click Shield for the socket you choose is set to GPIO. This should be the default out of the box setting. Note: Make sure your Pi is turned off when you do this!
- Turn on your Pi. After the Pi has started to boot up you should see the green LED on the Thunder Click board light up.
- That’s it for assembly. The rest is down to software.
Software
As mentioned above, not all Click Boards have Raspberry Pi software available for them. This is true for the Thunder Click board. There is some software available from other sources to use an AS3935 on a Pi but much of this is for using the chip on its I2C interface. The Thunder Click is configured to use the SPI (Serial Peripheral Interface) bus which meant that I’ve had to re-work some existing code to make it work.
There are a number of steps included in the software setup…
- Enable the SPI bus on the Raspberry Pi. See https://www.raspberrypi-spy.co.uk/2014/08/enabling-the-spi-interface-on-the-raspberry-pi/
- I’m using Python 3 to access the AS3935. You also need to use ‘pip’. If you’re running Raspberry Pi OS (previously called Raspbian OS) then you should have both Python 3 and pip installed by default. If you’re using another OS or installed a version of the Raspberry Pi OS without Python 3/pip included please install them using the appropriate method for your OS.
- Create a directory “/home/pi/Sensors” for the AS3935 software. You can name the directory as you wish, but I’m using Sensors here so that I can refer to it consistently.
- Install the pigpio library. At the time of writing there are different ways to do this depending on whether you’re using a Raspberry Pi 4 or not. The ‘long’ method is appropriate for any Raspberry Pi but must be used for the Pi 4. A shorter method can be used for a Raspberry Pi 3 (or 2). The Pi 4 requires version 76 of the library and that’s not yet available in the Python (pip) library which is why the longer method must be used to install the latest version of the library.
[li]Use this short method to install the pigpio library onto a Raspberry Pi 3 (or 2). Type these commands into a Pi terminal session:
sudo apt-get update
sudo apt-get install pigpio python-pigpio python3-pigpio
[/li]
[li]Use this longer method to install the pigpio library onto a Raspberry Pi 4. Type the following commands into a Pi terminal session:
sudo apt install python-setuptools python3-setuptools
cd Sensors
wget https://github.com/joan2937/pigpio/archive/master.zip
unzip master.zip
cd pigpio-master
make
sudo make install
If you want to test that the installation works properly you can use the following commands. This step is optional but may be required if you have problems getting pigpio working. The tests will probably take 5-10 minutes to complete.
sudo ./x_pigpio # check C I/F
sudo pigpiod # start daemon
./x_pigpiod_if2 # check C I/F to daemon
./x_pigpio.py # check Python I/F to daemon
./x_pigs # check pigs I/F to daemon
./x_pipe # check pipe I/F to daemon
The results of the tests should be fairly obvious. I get the error ‘ERROR: No more CBs for waveform’ when running the x_pigs test. This doesn’t appear to affect what we need to use the library for. At the end of the installation/test type ‘cd …’ to return to the ‘Sensors’ directory.
[/li]
The next steps start to cover the Python software. This is still a work in progress. For now, I’ve converted an AS3935 library written for an I2C connection to use SPI. There are also Python3 programs to test that you can connect to the AS3935, find the best calibration setting and do some simple monitoring of the AS3935 to report lightning to the console.
- Download the attached ‘AS3935_v2.zip’ file, upload it to your Pi and unzip it into the Sensors directory.
- If your Thunder Click is plugged into socket 1 of the Click Shield you must modify as3935_pigpio_test.py, calibrate_pig.py and thunder_interrupt.py as follows. Edit each file, e.g. using ‘nano’, and find the line containing ‘as3935 = RPi_AS3935(bus=0, address=1, mode=0b10, speed=400000)’. Change ‘address=1’ to ‘address=0’. Save the modified file.
[li]Run as3935_pigpio_test.py by typing
python3 as3935_pigpio_test.py
You should get some output like:
pi@raspberrypi:~/Sensors $ python3 as3935_pigpio_test.py
Test starting
Register 0x00 is 0x24
Register 0x01 is 0x02
Register 0x02 is 0xC2
Register 0x03 is 0xC0
Register 0x04 is 0x00
Register 0x05 is 0x00
Register 0x06 is 0x00
Register 0x07 is 0x3F
Register 0x08 is 0x0A
Test complete
The displayed values may vary depending on the exact initial state of your AS3935. If your hardware isn’t set up correctly then you will either see an error or possibly all 0x00 or 0xFF values displayed. Getting similar numbers to those above is a good sign that everything is working properly.
[/li]
[li]Next you need to calibrate the AS3935 to find the correct antenna tuning capacitance for lightning detection. The antenna needs to be tuned to 500kHz +/- 3.25% and part of register 0x08 is used to set the capacitance. To find the best capacitance to use for your AS3935 module run calibrate_pig.py by typing:
python3 calibrate_pig.py
The calibration run will take about 16 seconds (or longer if you’ve changed the ‘increment_time’ variable). At the end of the run you should get some output like this…
pi@raspberrypi:~/Sensors $ python3 calibrate_pig.py
Starting calibration run - Please wait approximately 16 seconds
Success!
Tuning Capacitor setting - 0x0A - 80 pF
Percent variance = 0.04 %
The important value is the ‘0x0A’ (or equivalent number for your module). Make a note of the value because you’ll need to edit it into other programs or config files. If you forget it you can always re-run the calibrate_pig.py program to get it again.
It’s possible to get a failure reported by the calibration run. This happens when none of the tuning capacitor values can tune the antenna within 3.25% of 500kHz. This possibly indicates faulty hardware but there can be other reasons for this, e.g. having the wrong configuration values defined in the calibration program.
[/li]
[li]Edit the thunder_interrupt.py program, e.g. using ‘nano’, to set the calibrated capacitance value for your module. Find the line ‘as3935.calibrate(tun_cap=0x0A)’ and change the value ‘0x0A’ to your own calibration value from the calibration run (see above).
[/li]
[li]
Run the thunder_interrupt.py script by typing:
python3 thunder_interrupt.py
You should see some output something like this displayed…
pi@raspberrypi:~/Sensors $ python3 thunder_interrupt2.py
Configured to run with antenna tuning capacitance of 80 pF
Waiting for lightning…
Press Ctrl+C to exit.
Noise level too high. Raising noise floor.
Noise level too high. Raising noise floor.
You may see no noise level entries, or multiple of them depending on how electrically noisy your location is. You might also see disturbers reported. These are other strong local signals that don’t fit the pattern for lightning. When this software sees the first disturber it disables disturbers from being reported for the duration of the run. If you’re lucky and there’s local lightning you’ll also see lightning strikes, with their estimated distance and energy, reported.
[/li]
thunder_interrupt.py configures the AS3935 for indoor use, sets the noise floor and sets the antenna tuning capacitance. These probably aren’t optimal settings for all use but you can change the settings if you like. The code probably isn’t written well, or optimised, but it’s for demo purposes only to check that you can access the Thunder Click from Python and that it detects a high noise floor, disturbers and, when there is some, detects lightning strikes.
After the config is done, it adds an interrupt handler function. Simply put, when the AS3935 wants to signal that something has happened, e.g. lightning has been detected, or the noise level has changed, etc, it interrupts the Raspberry Pi (using GPIO 26) which causes the ‘handle_interrupt’ code to be executed. This code looks at register 0x03 of the AS3935 to find out the reason for the interrupt and then displays it on screen. After the interrupt has been handled it goes back to waiting for the next interrupt.
This is the end of the first stage. If you’ve completed all these steps then you’ve got a functional AS3935 that can be accessed by Python. I’ve got a basic web server nearly ready to go that will display the data in a nicer way and will also allow a ‘nowcast.txt’ file to be accessed via the web server. This file should allow Weather Display to read the lightning data generated by the AS3935. I’ll post this code when it’s ready and documented.
Note: This configuration isn’t production ready yet. For example, you’ll need to manually restart pigpiod and the python software if you reboot the Pi. I’ll work on those after I get the first version of the web server published.
AS3936_v2.zip (7.9 KB)