This is version 3.2 of the AS3935 Lightning Detector for Raspberry Pi project. It is a very different program than the previous v1/2 releases. You shouldn’t need to rebuild your Pi if you’ve started setting up with version 1/2, but I would recommend renaming your ‘Sensors’ directory and then creating a new empty ‘Sensors’ directory before installing this version. This version will install and run over the previous versions but if you want to be able to roll-back to the previous version or keep your data/config files then you must ensure you have a copy before you proceed with this installation.
This is still 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/knowledge you can build it from individual parts/modules which is probably going to be cheaper. I have received a different AS3935 board and need to test it out. If you can solder (7 wires) to a small-ish board then you can save some money by using the second approach. I’ll document it when I’ve tested it.
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 already has 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.
- 1*Mikroe Pi 3 Click Shield - This is a Pi 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 instructions for the Click Shield 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. You will need to use the socket number (1 or 2) in the installation below. Ensure that 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 plug the module in!
- 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 software available for them on the Raspberry Pi. This is true in the case of the Thunder Click board. There is some software available to use an AS3935 but much of this is for using the chip on its I2C interface but the Thunder Click is configured to use the SPI (Serial Peripheral Interface) bus which meant that I had re-work some existing code to make it work. I understand that the AS3935 SPI interface is more reliable than the I2C interface so that’s good for this project.
The project has two different installation options. The first is a full install. This installs a monitor program and web server. The monitor runs in the background, managing the AS3935 and watching for events, e.g. lightning strokes. The web server allows you to see the status of the AS3935, e.g. event stats, current configuration and events as they occur. The monitor process sends data to the web server to be displayed as well as creating some JSON data files for use elsewhere if required.
The second installation option is just to install the monitor process. This allows the AS3935 to be managed and create some (but not all of the) JSON data files. It doesn’t have a way of displaying this data to you, other than looking at the files directly, nor does it have a way of reporting individual events.
It is expected that most users will want to use the full install option, but the monitor only option is provided for those who wish to have a cut down version that they use to display data/transfer data in other ways. If you’re not sure which option is best for you, you should probably choose the full install. Where the installation steps differ this will be noted at the end of the main instructions.
There are a number of steps required before the software can be installed/set up…
- 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/
- The software uses Python 3 to access the AS3935 and pip3 during the installation process. If you’re running Raspberry Pi OS (previously called Raspbian OS) then you will probably have both Python 3 and pip3 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. You can check if you have them installed by typing ‘python3’ in a terminal window. If you get a ‘>>>’ prompt then Python3 is installed (press Ctrl+D to exit Python). To check if you have pip3 installed, type ‘pip3’ in a terminal window. If you see help text displayed then pip3 is installed.
- Create a directory “/home/pi/Sensors” for the AS3935 software. At this time, the software MUST be installed into this directory. If you want to have the software in a different directory you will need to modify some files manually to enable this, e.g. the service unit file(s).
The next steps include the installation of some pre-requisite software and also the AS3935 Python software with the associate config/support files. This is done by uploading an installer file, extracting it and then using an installation script to complete the process. Most of these instructions need to be carried out in a terminal window, either one opened in the Pi Desktop or a remote one using software such as Putty. The instructions are the same whether done from the Pi Desktop or remotely. You will need to press the key after terminal window commands to run the command.
- If you have previously installed v1 or v2 of this software please stop the existing pigpiod background process before continuing. You can use ‘pkill pigpiod’ to stop the process.
- Download the attached ‘as3935_full_install_v3_2.zip’ file and upload it into the Sensors directory on your Pi. Software such as WinSCP can be used to make the upload fairly straightforward.
[li]Open a terminal window. You should be in the ‘/home/pi’ directory. Confirm this by typing ‘pwd’ to display the ‘present working directory’. If you’re in a different directory change into the correct directory by typing ‘cd /home/pi’. - Change into the Sensors directory by typing ‘cd Sensors’.
- Unzip the uploaded ZIP file using ‘unzip as3935_full_install_v3_2.zip’.
- Make the installer script executable by typing ‘chmod +x as3935_full_installer.sh’.
- The next step depends on which socket you installed your Thunder Click Board into. Replace ‘X’ with ‘1’ or ‘2’ for whichever socket you used. Run the installer script by typing ‘sudo ./as3935_full_installer.sh X’, e.g. ‘sudo ./as3935_full_installer.sh 2’. You must use sudo to run the installer to ensure that all files are copied to the correct locations. The installer will take up to a couple of minutes to run, depending on what software needs to be installed, the speed of your Internet connection and which model of Raspberry Pi you’re using. It will display progress information as it runs.
[li]When the installer has finished you should see some information displayed from a short test program. It looks something like this…
The test run results below should hopefully indicate that the installed version of pigpio is v77 or higher.
The register outputs should be something similar to 0x24, 0x07, 0xC2, 0xC0, 0x25, 0xE4, 0x07, 0x3F, 0x0A.
There will be some variance in the register values due to the unknown state of the AS3935 sensor in your
configuration. If they have completely different values, e.g. all 0x00 or 0xFF, then you will need to do
additional checks to ensure that your AS3935 is accessible in the expected way on your Raspberry Pi.
Test starting
Good version of pigpio found - Version 77
Register 0x00 is 0x24
Register 0x01 is 0x02
Register 0x02 is 0xC2
Register 0x03 is 0x00
Register 0x04 is 0x00
Register 0x05 is 0x00
Register 0x06 is 0x00
Register 0x07 is 0x3F
Register 0x08 is 0x0A
Test complete
Confirm that the pigpio is version is at least 77 and that the register values from your system are similar to those displayed. They may not be exactly the same but if they’re similar that’s a good result. If you see all the registers showing 0x00 then you may have selected the wrong socket number or forgotten to enter the socket number when running the installer from the command line.[/li] - Next edit the monitor configuration file by typing ‘nano as3935_monitor.config’. The file is documented explaining what each option does. Most values can initially be left as default. The only value to check is the ‘address’ value in the [as3935] section. This should be set depending on which socket your Thunder Click Board is plugged into. Note: The number here is NOT the socket number it is 0 or 1 denoting socket 1 or 2 respectively.
- Edit the web server configuration file by typing ‘nano as3935_web.config’. The file is again documented explaining what each option does. Most values can be left as default initially but please change the ‘secret_key’ value to a random set of characters for your installation.
- After editing the configuration files you can start the monitor and web server services (background processes) by typing ‘sudo systemctl start as3935_monitor.service’ and then ‘sudo systemctl start as3935_web.service’. Once started you can check the status of the services by typing ‘sudo systemctl status as3935_monitor.service’ and ‘sudo systemctl status as3935_web.service’. You should see a line including ‘Started AS3935 Monitor service’ or ‘Started AS3935 Web Server service’ which indicates that they started correctly. These services are re-started automatically each time you reboot your Pi. The monitor process can take over 2 minutes to start just after system startup if you have AUTO-calibration enabled. The calibration process is adversely affected if run whilst the Pi is starting up, i.e. when all the system startup processes are consuming a lot of CPU capacity.
- Now use your web browser to view the web server output. Navigate to ‘http://:5000’ to see the main page. In my case I navigate to ‘http://192.168.1.241:5000/’. It may take a little while (up to 1 minute or 3 minutes just after a reboot) after browsing to the web page before the full set of stats, events and settings are displayed. These are automatically updated on a regular basis if the page is left on display.
- You can also access the nowcast.txt data by browsing to ‘http://:5000/nowcast’, e.g. ‘http://192.168.1.241:5000/nowcast’ on my Pi. You can configure Weather Display to download the nowcast data from this URL and then import it. Note that from v3.2 you can also access the Nowcast data by browsing to ‘http://:5000/nowcast.txt’
- Version 3.2 also provides various JSON (JavaScript Object Notation) files via the browser. These can be imported into JavaScript pages on your own web pages to do whatever you want to with the data.
I have also provided the program calibrate_pig.py to carry out a manual calibration run. You can run the program using ‘sudo python3 calibrate_pig.py X’ where X is 1 or 2 depending on which socket you have plugged the Thunder Click Board into. Only run this program when the AS3935 monitor process is stopped (you can stop it using ‘sudo systemctl stop as3935_monitor.service’). By default the program will run for 16 seconds and provide the tuning capacitor setting that you can include in the as3935_monitor.config file if you wish. By default the monitor program will re-calibrate each time it’s run, just with a 16 second delay each time it’s started. I would recommend leaving the AUTO option enabled in the config file, but you can hard code the capacitor value using the calibration program information to get the tuning value if you want to. Note: The calibration needs to be within +/-3.5% for the sensor to run correctly. If the calibration program can’t find a value that is within tolerance then you will need to investigate why this is happening. If you see the best calibration value is nearly 100% wrong then you may have entered the wrong socket number or no socket number when running the program from the command line.
Monitor-only install
To just install the monitor component of the software, download the as3935_monitor_install_v3_2.zip file, upload and and unzip it. Once unzipped use (chmod then run) the as3935_monitor_installer.sh script in place of the as3935_full_installer.sh script described above. Prefix the installer command line with the socket number, e.g. ‘sudo ./as3935_monitor_installer.sh 2’. You don’t need to edit the as3935_web.config file (it’s not included) and only need to start the monitor service (the web server service files aren’t included). You will need to find a way to transfer/use the data created by the monitor in whatever way you wish to use it.
Upgrading from v3.0 or v3.1 to v3.2
- Stop the monitor and web services using ‘sudo systemctl stop as3935_monitor.service’ and ‘sudo systemctl stop as3935_web.service’.
- Download the appropriate installation .zip file and upload it into the Sensors directory on your Pi.
- Unzip the file, accepting any warnings about files being overwritten.
- Don’t run the installer script.
- There are some changes to the config files. The new versions are included in the .zip as ‘as3935_monitor.config.new’ and ‘as3935_web.config.new’. Edit your existing config files (‘as3935_monitor.config’ and ‘as3935_web.config’) to incorporate the changes. Open up two terminal windows side by side to allow you to see the current and new files side by side. I’m intending to make handling new config files easier in future but that’s not ready for v3.2.
- Start the monitor and web services using ‘sudo systemctl stop as3935_monitor.service’ and ‘sudo systemctl stop as3935_web.service’
Tested Pi Models and Operating systems
This project has been installed and operated on the following Raspberry Pi models and operating systems.
- 4GB Raspberry Pi Model 4B running Raspberry Pi OS Buster Full (Desktop plus recommended applications). Works from v3.0 of the AS3935 software. Running headless using Putty. No changes were required to the installation instructions provided above.
- 4GB Raspberry Pi Model 4B running Raspbian Buster. Works from v3.0 of the AS3935 software. Running headless using VNC. No extra software was installed.
- 1GB Raspberry Pi Model 3B running Raspberry Pi OS Buster Lite. Works from v3.1 of the AS3935 software. Prior to starting the install you will need to install pip3 for python using ‘sudo apt install python3-pip’.
- 1GB Raspberry Pi Model 3B+ running Raspberry Pi OS Buster Desktop. Works from v3.1 of the AS3935 software. No additional software required.
Thanks
Thanks are due to the people who helped me test the software, provided useful feedback and most importantly didn’t shout at me when I got things wrong. The testers, in alphabetical order, were Asobig, blainec, hcorrin, mihec, mldenison, pinto and smokie. Hopefully this and other similar projects will encourage more people to start experimenting with the Internet of Things. It’s really cool when you build something yourself that works and even better it does useful stuff! If you’ve got a project you’ve built, or want to build, that you can share with others here please feel free to document your progress so that others can follow you.
as3935_full_install_v3_2.zip (50.9 KB)
as3935_monitor_install_v3_2.zip (22.4 KB)