// USB to I2C Gateway used by AS3935.exe
// Copyright (C) muman.ch, 2025.10.23
//
// For details see
// https://muman.ch/muman/muman-as3935-lightning-sensor-app.htm

#include <Wire.h>

#include "SmallMessageProtocolSlave.h"
SmallMessageProtocolSlave slave;

#define IRQ_PIN 2


// Called when a full message is received, from slave.processMessages();
void processMessage(const byte* rxBuf, uint rxLength)
{
    // read info
    if (rxLength == 1 && rxBuf[0] == 2) {
        char* info = "MattLabs Lightning Detector v1.0";
        slave.sendAck((byte*)info, strlen(info) + 1);
        return;
    }

    // I2C write and get response
    //  0   1      2     3...
    // |01|i2cadds|txlen|txdata...|rxlen|
    if (rxLength >= 4 && rxBuf[0] == 1) {

        int i2cadds = rxBuf[1];
        int txlen = rxBuf[2];
        if (rxLength != txlen + 4) {
            slave.sendNak(4);
            return;
        }
        const byte* txdata = rxBuf + 3;
        int rxlen = rxBuf[3 + txlen];

        // i2c buffer is 32 bytes
        if (rxlen > 32) {
            slave.sendNak(5);
            return;
        }

        // i2c write bytes
        Wire.beginTransmission(i2cadds);
        if (Wire.write(txdata, txlen) != txlen) {
            slave.sendNak(6);
            return;
        }
        if (Wire.endTransmission(rxlen == 0) != 0) {
            slave.sendNak(6);
            return;
        }

        // sent ok, no response data
        if (rxlen == 0) {
            slave.sendAck(NULL, 0);
            return;
        }

        // i2c read bytes
        if (Wire.requestFrom(i2cadds, rxlen) != rxlen) {
            slave.sendNak(7);
            return;
        }
        byte response[32];
        if (Wire.readBytes(response, rxlen) != rxlen) {
            slave.sendNak(8);
            return;
        }

        // return the response
        slave.sendAck(response, rxlen);

        return;
    }

    // unknown command
    slave.sendNak(10);
}

void setup()
{
    //arduino zero
    //SerialUSB.begin(115200);

    Serial.begin(115200);

    Wire.begin();
    Wire.setClock(400000);
    Wire.setTimeout(300);

    pinMode(IRQ_PIN, INPUT);
    pinMode(LED_BUILTIN, OUTPUT);

    slave.begin(&Serial, processMessage);
}

void loop()
{
    slave.processMessages();
}

// Small Message Protocol Slave
// Copyright (C) muman.ch, 2025.10.23
// 
// For details see
// https://muman.ch/muman/muman-as3935-lightning-sensor-app.htm

#pragma once

typedef unsigned int uint;
typedef unsigned long ulong;


class SmallMessageProtocolSlave
{
protected:
    Stream* serial;

    // max. length is 255 (len in message is one byte)
    #define RXBUFLEN 100
    byte rxBuf[RXBUFLEN];
    uint rxState = 0;
    uint rxSeq;
    uint rxLength;
    uint rxIndex;
    uint16_t rxCsum;
    ulong rxTimer;

    // 0  1  2   3   4   5...          word
    // B7 C9 seq ack len data-bytes... csum 
    byte ackMsg[5] = { 0xB7, 0xC9, 0xff, 0x00, 0xff };

    // 0  1  2   3   4   5 6
    // B7 C9 seq nak len csum
    byte nakMsg[7] = { 0xB7, 0xC9, 0xff, 0xff, 0x00, 0xff, 0xff };

public:
    typedef void (*MessageReceivedDelegate)(const byte* msg, uint msglen);
    MessageReceivedDelegate messageReceivedHandler = NULL;

    void begin(Stream* serial, MessageReceivedDelegate messageReceivedHandler = NULL);
    void processMessages();
    void sendNak(uint reason);
    void sendAck(const byte* response, uint length);
    void sendAck();
    void sendMessage(const byte* response, uint length);

protected:
    uint calcCsum(uint csum, const byte* data, uint length);
};


void SmallMessageProtocolSlave::begin(Stream* serial, MessageReceivedDelegate messageReceivedHandler)
{
    this->serial = serial;
    this->messageReceivedHandler = messageReceivedHandler;
    rxState = 0;
}

// Ack response without data
void SmallMessageProtocolSlave::sendAck()
{
    sendAck(NULL, 0);
}

// Ack response with data
// 0  1  2   3   4   5...          word
// B7 C9 seq ack len data-bytes... csum 
void SmallMessageProtocolSlave::sendAck(const byte* response, uint length)
{
    ackMsg[2] = rxSeq;
    ackMsg[3] = 0x00;   // 0x00 = ack
    ackMsg[4] = (byte)length;
    uint csum = calcCsum(0xffff, ackMsg + 2, 3);
    if (length)
        csum = calcCsum(csum, response, length);
    serial->write(ackMsg, 5);
    if (length)
        serial->write(response, length);
    serial->write((byte*)(&csum), 2);
}

// Send unsolicited message to the master
// the sequence number is zero since it it not a response
void SmallMessageProtocolSlave::sendMessage(const byte* response, uint length)
{
    rxSeq = 0;
    sendAck(response, length);
}

// Nak response with nak reason 1..255
// 0  1  2   3   4   5 6
// B7 C9 seq nak len csum
void SmallMessageProtocolSlave::sendNak(uint nakReason)
{
    nakMsg[2] = rxSeq;
    nakMsg[3] = (nakReason == 0 || nakReason > 0xff) ? 0xff : (byte)nakReason;
    nakMsg[4] = 0;          // len=0, no data with nak response
    uint csum = calcCsum(0xffff, nakMsg + 2, 3);
    nakMsg[5] = (byte)csum;
    nakMsg[6] = (byte)(csum >> 8);

    serial->write(nakMsg, sizeof(nakMsg));
}

// 16-bit xor-and-rotate-right checksum of seq, length and data bytes
// start with 0xffff
uint SmallMessageProtocolSlave::calcCsum(uint csum, const byte* data, uint length)
{
    while (length--) {
        csum ^= *data++;
        if (csum & 1) {
            csum >>= 1;
            csum |= 0x8000;
        }
        else
            csum >>= 1;
    }
    return csum;
}

// State machine to receive a message
// calls the 'messageReceivedHandler' when a messge is received
void SmallMessageProtocolSlave::processMessages()
{
    // 0  1  2   3   4          word
    // B7 C9 seq len data-bytes csum
    while (serial->available()) {
        uint csum;
        byte b = serial->read();

        digitalWrite(LED_BUILTIN, rxState > 0);

        switch (rxState) {
        case 0:
            // 1st start byte 0xB7
            if (b == 0xB7) {
                rxTimer = millis();
                rxLength = 0;
                rxSeq = 0;
                rxState = 1;
            }
            break;

        case 1:
            // 2nd start byte 0xC9
            if (b == 0xC9) {
                rxState = 2;
                break;
            }
            rxState = 0;
            break;

        case 2:
            // sequence number byte
            rxSeq = b;
            rxState = 3;
            break;

        case 3:
            // data length byte
            rxLength = b;
            if (rxLength >= sizeof(rxBuf)) {
                //error
                sendNak(1);
                rxState = 0;
                break;
            }
            rxIndex = 0;
            rxState = 4;
            break;

        case 4:
            // buffer the data bytes
            if (rxIndex == RXBUFLEN) {
                // buffer overflow
                sendNak(2);
                rxState = 0;
                break;
            }
            rxBuf[rxIndex++] = b;

            // end of data
            if (rxIndex == rxLength)
                rxState = 5;
            break;

        case 5:
            // receiving csum ls byte
            rxCsum = b;
            rxState = 6;
            break;

        case 6:
            // receiving csum ms byte
            rxCsum += (uint)b << 8;

            // prepare to receive next message
            rxState = 0;

            // checksum validation
            csum = calcCsum(0xffff, (byte*)(&rxSeq), 1);
            csum = calcCsum(csum, (byte*)(&rxLength), 1);
            csum = calcCsum(csum, rxBuf, rxLength);
            if (rxCsum != csum) {
                sendNak(3);
                break;
            }

            // process received message
            if (messageReceivedHandler)
                messageReceivedHandler(rxBuf, rxLength);
            break;

        default:
            // invalid state?
            rxState = 0;
            break;
        }

        // receive message timeout
        if (rxState > 0 && (millis() - rxTimer) > 1000) {
            rxState = 0;
        }
    }
}

// Small Message Protocol Master
// Copyright (C) muman.ch, 2025.10.23
//
// For details see
// https://muman.ch/muman/muman-as3935-lightning-sensor-app.htm


using System;
using System.Diagnostics;
using System.IO.Ports;


namespace LightningDetector_WinForms
{
    public class SmallMessageProtocolMaster
    {
        public SerialPort port;

        // 1..255, increments for every message sent, rolls over to 1 after 255
        // this should be compared with the rxSeq of the response
        public uint rxSequenceNumber;

        // The ACK/NAK response of the last message, -1 = no response
        public int ackNakResponse = -1;

        // The first 4 bytes of the message, B7 C9 are the start bytes
        // 0  1  2   3   4...          word
        // B7 C9 seq len data-bytes... csum 
        protected byte[] msg = { 0xB7, 0xC9, 0xff, 0xff };


        public bool connect(string comPort)
        {
            try {
                rxSequenceNumber = 0;
                if (port != null)
                    disconnect();

                port = new SerialPort(comPort, 115200);
                port.ReadTimeout = 1000;    //ms
                port.WriteTimeout = 1000;

                //TODO sometimes it hangs here in port.Open()
                //GetCommState() or SetCommState() hangs - why?
                port.Open();

                return true;
            }
            catch (Exception ex) {
                Debug.WriteLine(ex.Message);
            }
            return false;
        }

        public void disconnect()
        {
            if (port != null) {
                port.Close();
                port = null;
            }
        }

        public bool messageReceived() { return port.BytesToRead != 0; }


        // 0  1  2   3   4...          word
        // B7 C9 seq len data-bytes... csum 
        public bool sendMessage(byte[] data, int offset, int count)
        {
            Debug.Assert(port != null);
            Debug.Assert(offset + count < 256);
            Debug.Assert(offset + count <= data.Length);

            if (++rxSequenceNumber > 255)
                rxSequenceNumber = 1;
            msg[2] = (byte)rxSequenceNumber;
            msg[3] = (byte)count;
            uint csum = calcCsum(0xffff, msg, 2, 2);
            csum = calcCsum(csum, data, (uint)offset, (uint)count);
            try {
                port.Write(msg, 0, 4);
                port.Write(data, offset, count);
                // re-use these 2 bytes for the checksum
                msg[2] = (byte)csum;
                msg[3] = (byte)(csum >> 8);
                port.Write(msg, 2, 2);
                return true;
            }
            catch (Exception ex) {
                Debug.WriteLine(ex.Message);
            }
            return false;
        }


        // 0  1  2   3   4   5...          word
        // B7 C9 seq ack len data-bytes... csum 
        public bool getResponse(byte[] rxData, out int rxDataLength, out int rxSeq, out int rxAckNak)
        {
            Debug.Assert(port != null);

            rxDataLength = 0;
            rxSeq = 0;
            rxAckNak = -1;

            uint rxState = 0;
            uint rxLen = 0;
            uint rxIndex = 0;
            uint rxCsum = 0;
            uint csum = 0;

            uint rxTimer = (uint)Environment.TickCount;

            do {
                while (port.BytesToRead > 0) {
                    int b = port.ReadByte();
                    if (b < 0) {
                        Debug.WriteLine("unexpected end of stream");
                        break;
                    }

                    switch (rxState) {
                    case 0:
                        // 1st start byte 0xB7
                        if (b == 0xB7) {
                            rxLen = 0;
                            rxSeq = 0;
                            rxState = 1;
                        }
                        break;

                    case 1:
                        // 2nd start byte 0xC9
                        if (b == 0xC9) {
                            rxState = 2;
                            break;
                        }
                        rxState = 0;
                        break;

                    case 2:
                        // sequence number byte
                        rxSeq = b;
                        rxState = 3;
                        break;

                    case 3:
                        // ack/nak byte, 0=ack, 1..255=nak reason
                        rxAckNak = b;
                        ackNakResponse = b;
                        rxState = 4;
                        break;

                    case 4:
                        // data length byte
                        rxLen = (uint)b;
                        if (rxLen > 256 || rxLen >= rxData.Length) {
                            Debug.WriteLine("invalid length");
                            rxState = 0;
                            return false;
                        }
                        rxIndex = 0;
                        // skip the data if there is none
                        rxState = rxLen == 0 ? 6u : 5;
                        break;

                    case 5:
                        // buffer the data bytes
                        if (rxIndex == rxData.Length) {
                            Debug.WriteLine("rx overflow");
                            rxState = 0;
                            return false;
                        }
                        rxData[rxIndex++] = (byte)b;

                        // end of data
                        if (rxIndex == rxLen)
                            rxState = 6;
                        break;

                    case 6:
                        // receiving csum ls byte
                        rxCsum = (byte)b;
                        rxState = 7;
                        break;

                    case 7:
                        // receiving csum ms byte
                        rxCsum += ((uint)b << 8);

                        // prepare to receive next message
                        rxState = 0;

                        // checksum validation
                        byte[] buf = new byte[3];
                        buf[0] = (byte)rxSeq;
                        buf[1] = (byte)rxAckNak;
                        buf[2] = (byte)rxLen;
                        csum = calcCsum(0xffff, buf, 0, 3);
                        csum = calcCsum(csum, rxData, 0, rxLen);
                        if (rxCsum != csum) {
                            Debug.WriteLine("invalid checksum");
                            return false;
                        }
                        rxDataLength = (int)rxLen;
                        return true;

                    default:
                        // invalid state?
                        rxState = 0;
                        break;
                    }
                }

            } while ((uint)Environment.TickCount - rxTimer < 1000);

            Debug.WriteLine("rx timeout");
            return false;
        }


        // 16-bit xor-and-rotate-right checksum of the seq, len and data-bytes
        // start with 0xffff
        protected uint calcCsum(uint csum, byte[] data, uint offset, uint count)
        {
            for (int i = 0; i < count; ++i) {
                csum ^= data[offset + i];
                if ((csum & 1) == 1) {
                    csum >>= 1;
                    csum |= 0x8000;
                }
                else
                    csum >>= 1;
            }
            return csum;
        }

    }
}

#pragma once

// AS3935 Lightning Sensor with I2C communications
// Copyright (C) muman.ch, 2025.10.16
// info@muman.ch
/*
This communicates with a translator running SmallMessageProtocolSlave() 
with the SerialToI2C app on the Arduino.

For full details of this code, see the blog entry:
https://muman.ch/muman/index.htm?muman-as3935-lightning-sensor-app.htm

DATA SHEET
All page references refer to THIS version of the data sheet
https://www.sciosense.com/wp-content/uploads/2023/12/AS3935-Data-Sheet.pdf

GRAVITY / DFROBOT MODULE
https://www.bastelgarage.ch/gravity-as3935-lightning-distance-sensor

THE OFFICIAL LIBRARY
The Mattlabs code below has several improvements on the official library.
https://github.com/DFRobot/DFRobot_AS3935/tree/master

*/

using System.Diagnostics;
using System.Threading;

namespace LightningDetector_WinForms
{
    public class AS3935LightningSensor
    {
        protected uint i2cAdds;
        protected SmallMessageProtocolMaster master;

        // Register bit masks taken from data sheet p19
        // the registers themselves do not have names, so we use the hex register numbers
        public enum MASK : uint
        {
            // 0x00 R/W
            AFE_GB =          0b00111110,   // AFE gain boost
            PWD =             0b00000001,   // 1=power down, 0=active
            // 0x01 R/W
            NF_LEV =          0b01110000,   // Noise floor level
            WDTH =            0b00001111,   // Watchdog threshold
            // 0x02 R/W
            CL_STAT =         0b01000000,   // Clear statistics, toggle high-low-high
            MIN_NUM_LIGH =    0b00110000,   // Minimum strikes for INT
            SREJ =            0b00001111,   // Spike rejection
            //0x03 R/W
            LCO_FDIV =        0b11000000,   // Frequency divider for antenna tuning
            MASK_DIST =       0b00100000,   // Mask disturber INT
            INT =             0b00001111,   // Interrupt source
            // 0x04 R
            S_LIG_L =         0b11111111,   // Strike energy LS byte (21-bit value)
            // 0x05 R
            S_LIG_M =         0b11111111,   // Strike energy MS byte
            // 0x06 R
            S_LIG_MM =        0b00011111,   // Strike energy MMS byte
            // 0x07 R
            DISTANCE =        0b00111111,   // Distance estimation in km, p33
            // 0x08 R/W
            DISP_LCO =        0b10000000,   // IRQ has LCO signal, 500kHz / LCO_FDIV
            DISP_SRCO =       0b01000000,   // IRQ has SRCO signal, 1.1MHz
            DISP_TRCO =       0b00100000,   // IRQ has TRCO signal, 32.768kHz
            TUN_CAP =         0b00001111,   // Capacitor LCO tuning, 0..120pF in 8pF steps
            // 0x3A R
            TRCO_CALIB_DONE = 0b10000000,   // TRCO calibration done successfully
            TRCO_CALIB_NOK =  0b01000000,   // TRCO calibration failed
            // 0x3B R
            SRCO_CALIB_DONE = 0b10000000,   // SRCO calibration done successfully
            SRCO_CALIB_NOK =  0b01000000,   // SRCO calibration failed

            // Send direct command, write 0x96 to issue the command
            PRESET_DEFAULT =  0x3C,         // Set all registers to default values
            CALIB_RCO =       0x3D          // Calibrate internal RC oscillators, 2ms
        };

        // IRQ source, what set IRQ active, register 0x03:INT
        public enum IRQ_SOURCE : uint
        {
            INT_NH =    0b0001,     // Noise level too high
            INT_D =     0b0100,     // Disturber detected, disabled by MASK_DIST
            INT_L =     0b1000,     // Lightning detected, no. of events set by MIN_NUM_LIGH
            INT_PURGE = 0b0000      // Distance estimation changed due to event purge, p34
        };

        // Optimal AFE gains for setAFEGain()
        public enum AFEGAIN : uint
        {
            INDOOR = 0x12,          // default
            OUTDOOR = 0x0e
        };


        ///////////////////////////////////////////////////////////////////////////////
        // Control

        // Power up, reset the chip, set all registers to default values
        public bool begin(SmallMessageProtocolMaster master, uint i2cAddress)
        {
            this.master = master;
            this.i2cAdds = i2cAddress;

            // if powered down, power it up
            byte data;
            if (!readRegister(0x00, out data))
                return false;
            if ((data & (byte)MASK.PWD) != 0) {
                if (!powerUp())
                    return false;
            }

            // set all registers to default values
            //return reset();

            return true;
        }

        // Set all registers to their default values
        // always call calibrateOscillators() after reset()
        // takes 2ms
        public bool reset()
        {
            if (!writeRegister((uint)MASK.PRESET_DEFAULT, 0x96))
                return false;
            delay(2);
            return true;
        }

        // Power up 
        // always call calibrateOscillators() after powerUp()
        // takes 2ms
        // p36 
        public bool powerUp()
        {
            if (!writeRegister(0x00, (uint)MASK.PWD, 0))
                return false;
            // LCO startup time after power up is 2ms
            delay(2);
            return true;
        }

        public bool powerDown()
        {
            return writeRegister(0x00, (uint)MASK.PWD, 1);
        }

        // Calibrate the internal SRCO and TRCO oscillators
        // this must be done after every powerUp() or reset()
        // takes 2ms
        // p36
        public bool calibrateOscillators()
        {
            // calibrate RCO command
            if (!writeRegister((uint)MASK.CALIB_RCO, 0x96))
                return false;

            //TODO only if it is in power down mode?
            // toggle DISP_SRCO, as described in data sheet p36
            if (!writeRegister(0x08, (uint)MASK.DISP_SRCO, 1))
                return false;
            delay(2);
            if (!writeRegister(0x08, (uint)MASK.DISP_SRCO, 0))
                return false;
            delay(2);

            // did it work? test the CALIB_DONE and CALIB_NOK flags
            byte trco, srco;
            if (!readRegister(0x3a, out trco) || !readRegister(0x3b, out srco))
                return false;

            // calibration should have been done
            if ((trco & (uint)MASK.TRCO_CALIB_DONE) == 0 || 
                (srco & (uint)MASK.SRCO_CALIB_DONE) == 0) {
                Debug.WriteLine("calib not done");
                return false;
            }

            // calibration errors?
            if ((trco & (uint)MASK.TRCO_CALIB_NOK) != 0 || 
                (srco & (uint)MASK.SRCO_CALIB_NOK) != 0) {
                Debug.WriteLine("calib failed");
                return false;
            }
            return true;
        }

        // Clear statistics for lightning distance estimation over the last 15 minutes 
        // this sets the getStormDistance() value to 0x3f (out of range)
        // it does NOT affect the getStrikeEnergy() value
        // p35
        public bool clearStatistics()
        {
            // toggle CL_STAT bit high-low-high
            // (this code reads register 0x02 just once instead of three times)
            byte b;
            if (!readRegister(0x02, out b))
                return false;
            if (!writeRegister(0x02, (byte)(b | (byte)MASK.CL_STAT)))
                return false;
            if (!writeRegister(0x02, (byte)(b & ~(byte)MASK.CL_STAT)))
                return false;
            return writeRegister(0x02, (byte)(b | (byte)MASK.CL_STAT));
        }

        // Very naughty, but I HATE await
        public void delay(int ms)
        {
            Thread.Sleep(ms);
        }


        ///////////////////////////////////////////////////////////////////////////////
        // Data Values

        // Returns the estimated distance (the radius) to the leading edge of
        // the storm in kilometers : 1 = overhead .. 40 = 40km 
        // 63 (0x3f) = out of range or no storm detected
        // The value remains unchanged until a new estimate is ready, or until
        // clearStatistics() is called.
        // p33 figure. 43
        public bool getStormDistance(out uint km)
        {
            return readRegister(0x07, (uint)MASK.DISTANCE, out km);
        }

        // Returns the estimated energy of the latest lightning strike as
        // a 21-bit value, 0..0x1fffff (0..2'097'151)
        // It's a unitless magnitude, useful to compare with previous values.
        // The value remains unchanged until a new strike occurs or it's set 
        // to 0 when a Disturber Event is detected. It is NOT cleared by 
        // clearStatistics().
        // p32
        public bool getStrikeEnergy(out uint strikeEnergy)
        {
            Debug.Assert(sizeof(uint) == 4);
            strikeEnergy = 0;
            byte lsByte, msByte, mmsByte;
            if (!readRegister(0x04, out lsByte))
                return false;
            if (!readRegister(0x05, out msByte))
                return false;
            if (!readRegister(0x06, out mmsByte))
                return false;
            strikeEnergy = (uint)(((mmsByte & (byte)MASK.S_LIG_MM) << 16) + 
                (msByte << 8) + lsByte);

            return true;
        }

        // If the IRQ output is activated, wait 2ms, then use this to find the 
        // source of the interrupt.
        // Returns and IRQ_SOURCE value,
        //  1 = INT_NH Noise level too high
        //  4 = INT_D  Disturber detected, disabled by MASK_DIST
        //  8 = INT_L  Lightning detected, no. of events set by MIN_NUM_LIGH
        //  0 = INT_PURGE  Distance estimation changed due to clearStatistics() 
        //      call, see p34. 0 is only valid if IRQ goes high.
        // The INT value is set to zero when it is read.
        // p34
        public bool getIRQSource(out uint irqSource)
        {
            return readRegister(0x03, (uint)MASK.INT, out irqSource);
        }


        ///////////////////////////////////////////////////////////////////////////////
        // Configuration

        // Adjusts the AFE gain boost for indoor or outdoor use
        // AFEGAIN::INDOOR (default) or AFEGAIN::OUTDOOR are the recommended 
        // settings, but any value between 0x00 and 0x1F can be used
        // p28
        public bool setAFEGain(AFEGAIN afeGain)
        {
            return writeRegister(0x00, (uint)MASK.AFE_GB, (uint)afeGain);
        }

        public bool getAFEGain(out AFEGAIN afeGain)
        {
            uint data;
            bool ok = readRegister(0x00, (uint)MASK.AFE_GB, out data);
            afeGain = (AFEGAIN)data;
            return ok;
        }

        // Set the minimum number of lightning events in a 15 minute window
        // to set IRQ and generate the INT_L interrupt, 0..3=1|5|9|16
        // minStrikes : 0 = 1 strike (default);  1 = 5 strikes;
        //              2 = 9 strikes; 3 = 16 strikes
        public bool setMinimumStrikes(uint minStrikes)
        {
            return writeRegister(0x02, (uint)MASK.MIN_NUM_LIGH, minStrikes);
        }

        public bool getMinimumStrikes(out uint minStrikes)
        {
            return readRegister(0x02, (uint)MASK.MIN_NUM_LIGH, out minStrikes);
        }

        // Enable/disable the "disturber" interrupt INT_D with the
        // MASK_DIST bit, 0=enabled, 1=masked and disabled
        // p34
        public bool setDisturberEnabled(bool enabled)
        {
            return writeRegister(0x03, (uint)MASK.MASK_DIST, enabled ? 0u : 1u);
        }

        public bool getDisturberEnabled(out bool enabled)
        {
            enabled = false;
            if (!readRegister(0x03, (uint)MASK.MASK_DIST, out uint maskDist))
                return false;
            enabled = maskDist == 0 ? true : false;
            return true;
        }

        // Selects the threshold for the Noise Floor Limit
        // when the noise crosses this threshold it will issue the INT_NH 
        // interrupt and activate IRQ. This indicates that measurements
        // cannot be taken because of excessive background noise.
        // noiseFloorLevel : 0..7, level in microvolts RMS (default = 2)
        // p30 figure 41
        public bool setNoiseFloorLevel(uint noiseFloorLevel)
        {
            return writeRegister(0x01, (uint)MASK.NF_LEV, noiseFloorLevel);
        }

        public bool getNoiseFloorLevel(out uint noiseFloorLevel)
        {
            return readRegister(0x01, (uint)MASK.NF_LEV, out noiseFloorLevel);
        }

        // The watchdog threshold WDTH defines the signal level that causes 
        // entry to "Signal Verification Mode" where it determines if it's 
        // a strike or a disturber event, see p17. 
        // Increasing the threshold makes it less sensitive to disturbers,
        // but also makes it less sensitive to weak signals from distant 
        // lightning sources.
        // Sensitivity is also affected by SREJ, see setSpikeRejection().
        // wdogThreshold : 0..15 (default = 2)
        // p29 figure 40
        public bool setWatchdogThreshold(uint wdogThreshold)
        {
            return writeRegister(0x01, (uint)MASK.WDTH, wdogThreshold);
        }

        public bool getWatchdogThreshold(out uint wdogThreshold)
        {
            return readRegister(0x01, (uint)MASK.WDTH, out wdogThreshold);
        }

        // Spike rejection works together with the watchdog threshold to
        // determine if the signal is a lightning strike or a man-made 
        // disturber.
        // Increasing the value improves disturber rejection, but also 
        // makes it less sensitive to weak signals from distant lightning 
        // sources.
        // spikeRejection : 0..15 (default = 2)
        // p31, p32 figure 42 
        public bool setSpikeRejection(uint spikeRejection)
        {
            return writeRegister(0x02, (uint)MASK.SREJ, spikeRejection);
        }

        public bool getSpikeRejection(out uint spikeRejection)
        {
            return readRegister(0x02, (uint)MASK.SREJ, out spikeRejection);
        }


        ///////////////////////////////////////////////////////////////////////////////
        // Calibration

        // When calibrating the LCO antenna oscillator's resonant frequency, 
        // the oscillator frequency must be output on the IRQ pin so it can 
        // be accurately tuned to 500kHz +-3.5% with setTuningCapacitor().
        // A frequency divider LCO_FDIV (16|32|64|128) for the LCO 500kHz is 
        // set with setLCOFrequencyDivider().
        // n : 0 = return to normal IRQ operation
        //     1 = output the LCO antenna oscillator frequency, 500kHz / LCO_FDIV
        //     2 = output the SRCO system RC oscillator, 1.1MHz
        //     3 = output the TRCO timer RC oscillator, 32.768kHz
        // >>> DO NOT FORGET to call selectIRQOutput(0) to set the IRQ pin 
        //     back to normal operation <<<
        // You may also want to check the system RC oscillator or the timer 
        // RC oscillator frequencies too.
        // p36
        public bool setIRQOutput(uint n)
        {
            Debug.Assert(n < 4);

            uint data = 0;
            switch (n) {
            case 1:
                data = (uint)MASK.DISP_LCO;
                break;
            case 2:
                data = (uint)MASK.DISP_SRCO;
                break;
            case 3:
                data = (uint)MASK.DISP_TRCO;
                break;
            }
            const uint mask = (uint)MASK.DISP_LCO | (uint)MASK.DISP_SRCO | (uint)MASK.DISP_TRCO;

            return writeRegister(0x08, mask, data >> 5);
        }

        public bool getIRQOutput(out uint n)
        {
            n = 0;
            const uint mask = (uint)MASK.DISP_LCO | (uint)MASK.DISP_SRCO | (uint)MASK.DISP_TRCO;
            if (!readRegister(0x08, mask, out uint data))
                return false;
            // only 1 bit should be set
            switch(data) {
            case 0:
                n = 0;
                break;
            case 1:
                n = 3;
                break;
            case 2:
                n = 2;
                break;
            case 4:
                n = 1;
                break;
            default:
                Debug.WriteLine("invalid IRQ output");
                break;
            }
            return true;
        }

        // When tuning the antenna and outputing the LCO resonant frequency
        // on the IRQ pin, see selectIRQOutput(), the LCO frequency is 
        // divided by 16|32|64|128 to give a lower frequency output.
        // fdiv : 0 = divide by 16 (default); 1 = 32; 2 = 64; 3 = 128
        // the LCO oscillator '500kHz / 16' should be 31.250kHz
        // p35
        public bool setLCOFrequencyDivider(uint fdiv)
        {
            return writeRegister(0x03, (uint)MASK.LCO_FDIV, fdiv);
        }

        public bool getLCOFrequencyDivider(out uint fdiv)
        {
            return readRegister(0x03, (uint)MASK.LCO_FDIV, out fdiv);
        }

        // The LCO antenna oscillator resonant frequency must be 500kHz +-3.5%.
        // This tunes the resonant frequency by selecting the internal capacitors
        // in steps of 8pf from 0..120pf. This varies the frequency by up to 25kHz.
        // The resonant frequency can be verified by outputing the signal on the 
        // IRQ pin, see selectIRQOutput(). The frequency see on the pin is divided 
        // by LCO_FDIV, see setLOCFreuqncyDivider().
        // tuneCap : 0 = 0pF; 1 = 8pF; 2 = 16pF; ..; 15 = 120pF
        // p35
        public bool setTuningCapacitor(uint tuneCap)
        {
            return writeRegister(0x08, (uint)MASK.TUN_CAP, tuneCap);
        }

        public bool getTuningCapacitor(out uint tuneCap)
        {
            return readRegister(0x08, (uint)MASK.TUN_CAP, out tuneCap);
        }


        ///////////////////////////////////////////////////////////////////////////////
        // Internal methods

        // Reads the register bits defined by 'mask' and shifts them right 
        // (normalises) so the LS bit of *data is the LS bit of the mask.
        public bool readRegister(uint reg, uint mask, out uint data)
        {
            data = 0;

            Debug.Assert(mask != 0 && mask <= 0xff);

            byte b;
            if (!readRegister(reg, out b))
                return false;
            if (mask == 0xff) {
                data = b;
                return true;
            }
            // shift data according to the bit mask
            b &= (byte)mask;
            for (uint i = mask; (i & 1) == 0; i >>= 1) {
                b >>= 1;
            }
            data = b;
            return true;
        }

        // Writes register bits in 'mask' with 'newData' without modifying any other
        // bits. 'newData' is shifted left to fit the mask. Returns false if the
        // data will not fit the mask.
        public bool writeRegister(uint reg, uint mask, uint newData)
        {
            Debug.Assert(mask != 0 && mask <= 0xff);

            byte data;
            if (mask == 0xff) {
                // use all the bits
                data = (byte)newData;
            }
            else {
                // read existing value
                if (!readRegister(reg, out data))
                    return false;
                // shift new data according to the bit mask
                for (uint i = mask; (i & 1) == 0; i >>= 1) {
                    newData <<= 1;
                }
                // make sure new data fits the bit mask
                if ((newData & ~mask) != 0) {
                    Debug.WriteLine("data+mask error");
                    return false;
                }
                // mask out existing data and replace with new data
                data = (byte)((data & ~mask) | newData);
            }

            // write the new data
            return writeRegister(reg, data);
        }

        // Change these according to the comms protocol

        // I2C write and get response
        //  0   1      2     3...
        // |01|i2cadds|txlen|txdata...|rxlen|
        protected byte[] readRegMsg  = { 0x01, 0xff, 0x01, 0xff, 0x01 };
        protected byte[] writeRegMsg = { 0x01, 0xff, 0x02, 0xff, 0xff, 0x00 };
        protected byte[] rxData = new byte[32];

        protected bool readRegister(uint reg, out byte data)
        {
            data = 0;

            readRegMsg[1] = (byte)i2cAdds;
            readRegMsg[3] = (byte)reg;

            if (!master.sendMessage(readRegMsg, 0, 5))
                return false;

            int rxDataLength, rxSeq, ackNak;
            if (!master.getResponse(rxData, out rxDataLength, out rxSeq, out ackNak))
                return false;

            if (ackNak != 0) {
                Debug.WriteLine("nak response " + ackNak);
                return false;
            }
            if (rxDataLength != 1) {
                Debug.WriteLine("rxDataLength != 1");
                return false;
            }
            data = rxData[0];
            return true;
        }

        protected bool writeRegister(uint reg, uint data)
        {
            writeRegMsg[1] = (byte)i2cAdds;
            writeRegMsg[3] = (byte)reg;
            writeRegMsg[4] = (byte)data;

            if (!master.sendMessage(writeRegMsg, 0, 6))
                return false;

            int rxDataLength, rxSeq, ackNak;
            if (!master.getResponse(rxData, out rxDataLength, out rxSeq, out ackNak))
                return false;

            if (ackNak != 0) {
                Debug.WriteLine("nak response");
                return false;
            }
            if (rxDataLength != 0) {
                Debug.WriteLine("rxDataLength != 0");
                return false;
            }
            return true;
        }

#if DEBUG
        public bool dumpRegisters()
        {
            byte b;
            for (uint i = 0; i <= 8; ++i) {
                if (!readRegister(i, out b))
                    return false;
                Debug.WriteLine(string.Format("{0:X2} 0x{1:X2}", i, b));
            }
            for (uint i = 0x3a; i <= 0x3b; ++i) {
                if (!readRegister(i, out b))
                    return false;
                Debug.WriteLine(string.Format("{0:X2} 0x{1:X2}", i, b));
            }
            Debug.WriteLine("");
            return true;
        }
#endif

    }
}