Kaminari

This is an ESP8266 and AS3935 based Franklin Lightning Detector. It connects to a WiFi network, and offers a JSON web service for detected lightnings.

WARNING: This project is for educational purposes only. This is just a toy. It is not intended to be used as an early warning indicator for lightning related storms. It does not guarantee accuracy or predict exact strike locations. It it not a replacement for a professional lightning detector. Again: This is just a toy.

Features

Small size and low power consumption
Can be read out and configured via HTTP web service and JSON
Lightnings can be reported via MQTT
Optional RGBW LED for showing the system status and detected lightnings
Self-calibrating detector
Permanent automatic noise floor level adjustment

Building and Installation

Prototype

Hardware

You need:

An ESP8266 module. You can use any brand, as long as it provides a regulated 3.3 V power source, and exposes the SPI interface and GPIO 5.
An AS3935 Franklin Lightning Detector module. Again, no special brand is required, as long as the SPI interface is exposed.

The lightning detector is connected like this:

Vcc → 3.3 V power output of the ESP board
SCL → CLK (IO14)
MOSI → MOSI (IO13)
MISO → MISO (IO12)
CS → CS (IO15)
IRQ → IO5

All other terminals of the detector are connected to GND of the ESP board.

Optionally, a single SK6812 RGBW LED can be added as a status LED. It is must be powered by 5 V, and its data input is directly connected to IO4.

No other components are required.

To fully understand the functionality of the lightning detector, please read the AS3935 datasheet.

Important Notes

The ESP8266's WiFi is disturbing the AS3935 detector, and reducing the quality of lightning detection up to a point where lightnings cannot be detected at all. Make sure there is sufficient space between both boards! There should be at least 10 cm between the WiFi antenna and the detector coil. The more space, the better.

Some manufacturers of the lightning detector print a calibration value on the package. As Kaminari calibrates the detector automatically, the calibration value is not needed.
Some AS3935 boards are equipped with non-standard parts in the antenna RC, and thus cannot be tuned to the recommended frequency of 500 kHz. If you're lucky, it is still within the required tolerance of ±3.5%. Those boards can be used, but may give inferior results. It is not a fault of Kaminari if the exact frequency is missed. (I got multiple reports about CJMCU boards having this issue, and can confirm it with my own board of this brand.)

Firmware

To build the firmware, you need to install the Arduino IDE. After installation, just open the kaminari.ino file.

Dependencies

Please make sure these libraries are installed in the Library Manager of the Arduino IDE:

Configuration

Before you build the project for the first time, please copy the myWiFi.h.example file to myWiFi.h, and adapt it to your needs:

MY_SSID: The SSID of your WLAN to connect to
MY_PSK: The password of your WLAN
MY_APIKEY: Your API key for endpoint calls that change the state of the detector. You can set a random, password-like word here.
MY_MDNS_NAME: Your preferred mDNS name. Just use the default value kaminari if you don't know what to use here.

To send lightning events via MQTT, these additional options need to be configured:

MY_MQTT_ENABLED: This line needs to be commented in to activate MQTT support. MQTT is disabled by default.
MY_MQTT_SERVER_HOST: Host name of the MQTT server.
MY_MQTT_SERVER_PORT: Port of the MQTT server (default is 1883).
MY_MQTT_USER: MQTT authentication user name
MY_MQTT_PASSWORD: MQTT authentication password
MY_MQTT_TOPIC: MQTT topic to be used
MY_MQTT_RETAIN: true if messages shall be retained. Default is false.

Installation

Now you can build the project in ArduinoIDE.

After that, connect your ESP8266 via USB. In the Tools menu, please set all parameters so you can upload the sketch to your ESP8266. The settings depend on the brand of your module and on your computer's operating system, so there are no generic settings that can be recommended here.

When everything is completed, upload the sketch to your module. That's all.

You can open the Serial Monitor to read some debug output of Kaminari as it starts up. You will find the WiFi status, the IP address, and the calibration results there.

Connection

There is a small web server running in Kaminari. You can connect to it by pointing your browser to the IP address (e.g. http://192.168.1.23/status).

Kaminari uses mDNS. If your operating system supports it, you can also connect to the sensor via http://kaminari.local/status (or whatever mDNS name you have used in your myWiFi.h file).

Endpoints

Kaminari offers a set of endpoints. Some endpoints are read-only. Other endpoints change the state of the detector, and thus require the API key to be passed in via X-API-Key header or api_key URL parameter. For the sake of simplicity, all requests are GET requests, even those that change the state of the detector.

`/status`

Returns the current status of the detector as JSON structure. This is an example result:

{
    "lightnings": [
        {
            "age": 34,
            "distance": 12,
            "energy": 38123
        }
    ],
    "distance": null,
    "energy": 0,
    "noiseFloorLevel": 146,
    "disturbersPerMinute": 81,
    "watchdogThreshold": 1,
    "wifiSignalStrength": -55
}

This is the meaning of the individual properties:

lightnings: An array of detected lightnings. It contains the age of the event (in seconds), the estimated distance of the lightning (in kilometres) and the lightning energy (no physical unit). Kaminari stores up to 64 lightning events, and returns them in antichronological order. When a 65th event is recorded, the oldest record will automatically be removed from the list. This array is empty if no lightnings have been detected yet.
distance: General distance of the storm, in kilometres. null means that the storm is out of range, while 1 means that the storm is overhead. May also contain values caused by disturbers. For debugging purposes only, may be removed in a future version.
energy: General energy of detected lightnings, with no physical unit. May also contain values caused by disturbers. For debugging purposes only, may be removed in a future version.
noiseFloorLevel: Current noise floor level, in µVrms. Kaminari raises or lowers the level automatically, depending on the level of environment radio noises.
disturbersPerMinute: Number of detected disturbers per minute. The value should be as low as possible for best results. Higher values mean that the detector is receiving a lot of disturbing radio noises.
watchdogThreshold: Current watchdog threshold. Range is between 0 and 10. Higher values mean lower sensibility against disturbers, but also lower sensibility against very far lightning events.
wifiSignalStrength: Current WiFi received signal strength, in dBm.

`/settings`

Returns the current settings of the detector as JSON structure, for example:

{
    "tuning": 500135,
    "noiseFloorLevel": 146,
    "outdoorMode": false,
    "watchdogThreshold": 2,
    "minimumNumberOfLightning": 1,
    "spikeRejection": 2,
    "statusLed": true,
    "blueBrightness": 48,
    "disturberBrightness": 100
}

tuning: The tuning of the internal antenna, in Hz. Should be around 500 kHz, with a tolerance of ±3.5%.
noiseFloorLevel: Current noise floor level, in µVrms.
outdoorMode: true if the detector is switched to outdoor mode. In outdoor mode, a higher noise floor level voltage is used for suppressing disturbers. If the LED is blinking blue, you can try to enable the outdoor mode to make the device less sensitive for disturbers.
watchdogThreshold: Current watchdog threshold, see AS3935 datasheet.
minimumNumberOfLightning: Minimum number of lightnings until a lightning detected event is triggered.
spikeRejection: Current spike rejection, see AS3935 datasheet.
statusLed: If true, the status LED displays signal quality and detected lightnings. If false, the status LED will only display important system states (WLAN disconnected, calibration in progress) and is turned off otherwise.
blueBrightness: Maximum brightness of the blue LED indicating the noise floor level.
disturberBrightness: Brightness of the LED when a disturber is detected.

`/update`

This endpoint permits to change the settings. Settings to be changed are passed as URL parameter:

outdoorMode: Enable or disable the outdoor mode.
watchdogThreshold: Watchdog threshold, between 0 and 10, see AS3935 datasheet. Higher numbers give better robustness against disturber signals, but a lower lightning detection rate.
minimumNumberOfLightning: Minimum number of lightnings until a lightning detected event is triggered. Only 1, 5, 9, and 16 are permitted, other values will be ignored.
spikeRejection: Spike rejection, between 0 and 11, see AS3935 datasheet. Higher numbers give better robustness against disturber signals, but a lower lightning detection rate.
statusLed: Change the status LED operation.
blueBrightness: Maximum brightness of the blue LED indicating the noise floor level, between 0 and 255. 0 turns the constant blue light off, wh

Kaminari

Install / Use

README

Kaminari

Features

Building and Installation

Hardware

Important Notes

Firmware

Dependencies

Configuration

Installation

Connection

Endpoints

`/status`

`/settings`

`/update`