Can the I2C ADS1115 be configured in Tasmota?

[ullix]

The ADS1115 is a 4x ADC of 16bit. It is supported in Generic Tasmota, and when connected via I2C it brings Web_sensor answers like:

ADS1115 Analog0	20574
ADS1115 Analog1	0
ADS1115 Analog2	0
ADS1115 Analog3	0

I would like it to show not binary readout (like 20574) but voltage (here: 3.846 V), and want to see only the "0" channel. Also, it can be configured fo 6 different scales; here by default the maximum "±6.144V" scale is configured.

I am unable to find any means to configure this output. Is it even possible?

[sfromis]

See command Sensor12.

[ullix]

Aha, "Sensor12" for an I2c device indexed at "13".

I am now getting on command "Sensor12 S1": RESULT = {"ADS1115":{"Settings":"S1","Mode":"Single ended","Range":4096,"Unit":"mV"}}
The range is changed as desired, and it says: "Unit":"mV". That is not even close. The output is actually:

STATUS10 = {"StatusSNS":{...,"ADS1115":{"A0":28345,"A1":28427,"A2":28379,"A3":28407}, ...}}

These are the 16-bit readout values. What am I missing - how can I configure a voltage readout?

And on the console and on the Web_Gui it shows all 4 possible values. I am using only the first. Can I suppress the other 3 from showing?

[meMorizE]

The Sensor12 command allows to change the PGA thus controlling the analog input range.
But the sensor driver always output a unitless 16 bit integer value (counts).

To convert and display a voltage value (or any other scaled output), you can use the rules system.
These discussions should help:

#15664

#15514

If you are using an ESP32, you can either try Berry, but I had not found direct examples.

And if you finally got your scaled output you can supress the display of the raw 16bit values at Webserver using this command:
WebsSensor12 0

To turn it on again:
WebSensor12 1

[ullix]

I can certainly re-program the ADS1115 Web showing - I do this with other sensors, that are not supported by default Tasmota. But why should I when it is already done, albeit with a bug? This command:

"Sensor12 S1": RESULT = {"ADS1115":{"Settings":"S1","Mode":"Single ended","Range":4096,"Unit":"mV"}}

ends with showing "Unit":"mV". This tells me, it is showing the value is unit "mV". But this is wrong! It shows a unitless 16 bit value! Ergo: this is a bug!

Fix this with a little calculation: The requirement for making the unit to "mV" is already laid down in the command response itself. It has a "Range":4096," entry. Take this to calculate "mV" by bitvalue / 2^15 * range and you got the "mV"! Remember that the range is meant as plus/minus range, going from -4096 to +4096, so 1 bit of the 16 is used as sign. (But beware: you cannot measure any voltage > SupplyVoltage + 0.3, nor should you ever connect any such higher voltage to the ESP!

If you need more convincing, here is a clip from the ADS1115 Datasheet:

[sfromis]

That "Unit":"mV" is simply a constant, and is not about what is shown as measured sensor values. What it does indicate is that "Range":4096 is in millivolts. As the Sensor12 command description says, selecting S1 is for a range of +/- 4.096v, also found in the datasheet page you screenshotted. The result message from the Sensor12 command reflects this without a decimal point, meaning that 4.096V correctly becomes 4096 in the unit of millivolts. End of story.

Having the sensor driver able to report measured values in volt instead of raw sensor data would be a new feature for the driver, not a bugfix. The driver does what it was intended to do. I'm certainly not trying to argue against such a new feature, and the logical unit to convert to would be V (as the standard voltage scaling in other places).

[ullix]

"Volt" is perfectly fine for me. Even preferred over "mV", I agree.

But what on earth can I do with a value of e.g. 27349? It is really hard for my limited brain to multiply this with 15.625 µV :-( 125µV is not better :-((

[sfromis]

You already yourself suggested how to convert the raw value to a voltage. You can automate that by creating a Berry driver acting to provide sensor values for the front page and JSON. Or "someone" could extend the core Tasmota driver to provide such a feature.

[ullix]

Presenting a binary readout as user info is probably the worst feedback possible!

I guess "someone" needs to fix that in the core driver. I'd make a pull request, but I guess "someone" would be insulted receiving a pull request for such a trivial matter :-/

[meMorizE]

An ADC typically does not measure voltage directly, it provides a ratio of an input value against a reference value.

Ok, In the case of the ADS1115 the reference value is provided internally by a low drift voltage reference, but at many other ADC's the reference need to be connected externally.

The raw value does not require the information of the reference, therefore this is more an universal approach in concern of a simple driver.

I ask this question myself during the development of an ADS1256 driver (work in progress).
Yes it looks nicer showing a voltage but this requires the reference information on driver level for every individual device.

In most cases the direct measured value is not the user application scale, so using rules or Berry for post-processing is quite obvious.

[ullix]

For completeness: I wondered about the precision of the ADS1115:
Setting at "4096", so we get 125 µV/LSB. I applied voltages from 0.5 ... 3.8 V (thus even beyond the specs limit of Vsupply+0.3). The best I can say, within this range response is linear.

Testing precision around 3 V, I get, e.g.:

- setting power supply:     3.30 V
- measured by DMM:          3.305 V
- measured by ADS1115:      3.27 V  (slightly fluctuating; avg of 10 readings)

For me, factory setting is plenty good enough!

[ullix]

I remembered the result which @sfromis got Gemini AI coding, and tried it for the ADS115. Well, on first glance it looked good, but I got bugs (use of "or" instead "||", and wrong use of nil), but even after fixing this, it did not deliver proper values.

After a deep look into the datasheet of the ADS1115 I found incorrect bit-wise configuration. With that also fixed, it worked:

The ugly binary values ("30780") are from Tasmota core, the shiny "3.827 V" are from my code. After all, easy to do. "Someone" could well use this code to update core!

class ADS1115
    ### see datasheet: https://www.ti.com/lit/ds/symlink/ads1115.pdf

    var addr
    var name
    var wire

    def init(addr)
        self.addr = (addr == nil) ? 0x48 : addr
        self.name = classname(self)
        self.wire = tasmota.wire_scan(self.addr)
        if self.wire
            tasmota.add_driver(global.ADS1115_instance := self)
            pri(f"{self.name:-10s} Init Success - Device 0x{self.addr:2X} detected on bus {self.wire.bus}")
        else
            pri(f"{self.name:-10s} Init FAILURE - sensor  {self.name} NOT found" )
        end
    end

    
    def read_adc(channel)
        ### Konfiguration und Start der Messung
        
        if !self.wire return nil end

        # Config Register (0x01):
        # Bit  15   : Start (1),
        # Bits 14-12: MUX (Kanal A0=0x4)
        # Bits 11-9 : Gain (+/-4.096V=0x1)
        # Bits 8    : Mode (Single-shot=1)
        # Bits 7-5  : Data Rate (128 SPS=0x4) 100b
        #                       (  8 SPS=0x0) 000b
        # Bits 4-0  : Keep at 00011b

        var config                    # Bit pos: 15      11      7       3
        if   channel == 0 config = 0xc283      # 1 100   001 0   100 0   0011   A0 gegen GND, +/-4.096V, Single-Shot
        elif channel == 1 config = 0xd283      # 1 101   001 0   100 0   0011   A1
        elif channel == 2 config = 0xe283      # 1 110   001 0   100 0   0011   A2
        elif channel == 3 config = 0xf283      # 1 111   001 0   100 0   0011   A3
        end

        # Schreibe Konfiguration (Register 0x01)
        var b = bytes()
        b.add(config >> 8, 1)                   # MSB
        b.add(config & 0xFF, 1)                 # LSB
        self.wire.write_bytes(self.addr, 0x01, b)

        ### read data
        var res  = self.wire.read_bytes(self.addr, 0x00, 2)  # Lese Conversion Register (0x00) - 2 Bytes (Big Endian)
        var val  = res.geti(0, -2)                           # Liest 2 Bytes als signed 16-bit Big Endian
        var volt = val * 0.000125                            # Umrechnung in Volt (für Gain +/-4.096V ist 1 LSB = 0.125mV)

        return volt
    end


    def getVolts()
        ### get and verify volts

        var v0 = self.read_adc(0)
        var v1 = self.read_adc(1)
        var v2 = self.read_adc(2)
        var v3 = self.read_adc(3)

        v0 = (v0 == nil) ? "nil" : f"{v0:0.3f}"
        v1 = (v1 == nil) ? "nil" : f"{v1:0.3f}"
        v2 = (v2 == nil) ? "nil" : f"{v2:0.3f}"
        v3 = (v3 == nil) ? "nil" : f"{v3:0.3f}"

        return [v0, v1, v2, v3]
    end


    def web_sensor()
        ### Tasmota Callback: Anzeige im Web UI

        var v = self.getVolts()
        var msg = string.format("{s}ADS1115 A0{m}%s V{e}"
                                "{s}ADS1115 A1{m}%s V{e}"
                                "{s}ADS1115 A2{m}%s V{e}"
                                "{s}ADS1115 A3{m}%s V{e}"
                                , v[0], v[1], v[2], v[3])
        tasmota.web_send_decimal(msg)
    end


    def json_append()
        ### Tasmota Callback: Anzeige via "Status 10"

        var v = self.getVolts()
        var msg = string.format(',"myADS1115":{"A0":%s, "A1":%s, "A2":%s, "A3":%s}'
                                 , v[0], v[1], v[2], v[3] )
        tasmota.response_append(msg)
    end
end
ads1115 = ADS1115(0x48)

[sfromis]

While that looks good, what I meant by creating a driver was not an alternate ADS1115 driver; but instead something like the old code Noschvie now posted a link to: The new driver getting the values from the existing driver, taking advantage of the customization setup available there, and then do the very simple calculations to present results as additional data along the native driver results.

It could be enhanced a bit by having it use the Sensor12 command to query the setup, and automatically adjust calculations to the selected range.

Still interesting that you got an almost workable driver using Gemini AI.

[Noschvie]

Did you have a look to this Berry driver ?

[ullix]

My clear preference would be that the current "core driver" (meaning, the one built into default Tasmota) would get an update to properly present Volts and considers the user calibration (6144, 4096, ...). I would happily prefer that code over my own!

The @Noschvie code lacks - like my own - the consideration of the scaling besides one, here 6144. Not sure how this is done in the core driver, but I'm afraid it is not trivial to do this via Tasmota?

But even as it is, it does cost performance. The call of tasmota.read_sensors() alone is twice as long as for all 4 channels of my code (28 ms plus remainder of the code vs 14 ms for my code). The core code might only be a weeny bit faster, as the I2C part is already C-code?

I am excited to have learned the tasmota.read_sensors() command! Not only is it faster than my "Status 10" calling (by 10...20%), but it also doesn't spoil the console log with all its output! Is there somewhere a webpage with all those command goodies?

[sfromis]

Having the boozeman driver respect the configured range should be very simple, replacing the start of the driver by something like this code (untested):

class ADS1115Data
  var convert_to_mv
  var multiplier
  
  def init()
    self.multiplier = tasmota.cmd('Status12', true)['ADS1115']['Range'] / 32767000.0
  end

  def ads1115()
    # Read needed Sensor data
    var sensors = json.load(tasmota.read_sensors())['ADS1115']
	
    # Calculate value in volts
    var adc_mv0 = sensors['A0'] * self.multiplier
    var adc_mv1 = sensors['A1'] * self.multiplier
    var adc_mv2 = sensors['A2'] * self.multiplier
    var adc_mv3 = sensors['A3'] * self.multiplier

Probably a little bit faster, but not significantly.

This illustrates how Berry code adjust the voltage range, in this case also accessing the configured value. Really, not at all hard to do.

[ullix]

Simple! Speaks to the flexibility of Tasmota. When combined with Berry!

[ullix]

There is a flaw in both the core code for the ADS1115, as well as in my-AI-inspired code! The problem is that the ADC conversion time is unsufficiently considered, which could result in completely false readings.

The conversion does take some time. Unsurprisingly, the more time you give the converter the lower the voltage scatter is. This speed can be configured at 8 levels from 8 SPS (Sample-per-Second) taking 165 ms, up to 860 SPS taking 13 ms.

Once a conversion has been done, it is held in the "Conversion Register" as a 16 bit value. It is overwritten with the next conversion, once that next one is completed. You can read the reg at any time. When you read the register while a conversion is ongoing, you get the previously completed result!

The crux is the following: you could have changed the channel before the latest read, and when you read too soon, you will get the PREVIOUS channel result, and believe it is the current one! Surely not what you want.

In the code the "too soon" is attempted to respect by adding a delay between config setting and reading. The core code (https://github.com/erocm123/Sonoff-Tasmota/blob/master/sonoff/xsns_12_ads1115.ino ) uses an 8 ms delay. And it uses the fastest conversion (and only that one, i.e. always the worst resolution). However, as I said above I see the fastest conversion taking 13 ms (+/- a few ms).

The AI-inspired code uses the default speed of 128 SPS, which needs 24 ms, and puts in a 10 ms delay. So, also insufficient!

The ADS1115 offers two ways to check for completion of a conversion, a hardware and a software one. The hardware uses another pin on the MCU for polling or interrupt. The software uses a bit in the config register, and you must loop for bit state. Don't forget an exit clause in case the chip fails!

I prefer the software solution. The code becomes mildly more complex, but you avoid nonsense data.

P.S. The core code claims a sampling range for the ADS1115 from 128 SPS up to 6000 SPS. No way! Even the ADS1015 (only a 12 bit ADC) cannot do more than 3300 SPS. See above for true range of the ADS1115. Looks like Copy&Paste-Code from a different chip. You won't notice, because you cannot change SPS; it is coded as a 3 bit value, and 111b is the highest value anyway, and this is used.

[meMorizE]

Nice analysis, fully agree, there is much room for improvements and fixes.

Things I also don't like:

• redundant execution of a conversion-loop at the 250ms API-call (rules are typically active) AND at the Show API-call
• Hard-coded 1% change (full scale) update-trigger for the 250ms-API rules acquisition
• multi-device parallelism not implemented: devices can start and convert parallel, only channels need to be serialized

I have already created a branch in my fork to try things out, but I can't promise a PR soon.
Also working on an ADS1256 driver (24bit, 8 Channels, SPI) which has a few more configuration registers.