ads1256.py

Go to the documentation of this file.

#!/usr/bin/env python3
# ads1256.py
#
# Copyright (c) 2020-2022 Spring City Solutions LLC and other contributors
# Licensed under the Apache License, Version 2.0
#
# Need to have the rpi.gpio and spidev python libraries installed
#
# For development, need to install the pytest system.
# sudo apt-get install python3-pytest
# See also tests/ads1256_test.py
# Running 'python -m pytest' should result in no errors
#
# For development, need to install the flake8 system.
# sudo apt-get install python3-flake8
# Running flake8 should report no serious problems,
# with E501 being ignored and excluding tests/
#
# Hardware Links:
#
# Board Manufacturer Store:
# https://www.waveshare.com/High-Precision-AD-DA-Board.htm
#
# Board Manufacturer Wiki:
# https://www.waveshare.com/wiki/High-Precision_AD/DA_Board
#
# Links for ADS1256 chip:
# https://www.ti.com/product/ADS1256
# https://www.ti.com/lit/gpn/ads1256
# Book "Fundamentals of Precision ADC Noise Analysis" https://www.ti.com/lit/pdf/slyy192
# Journal Series "How delta-sigma ADCs work" https://www.ti.com/lit/pdf/slyt423 https://www.ti.com/lit/pdf/slyt438
# App Note "Digital Filter Types in Delta-Sigma ADCs" https://www.ti.com/lit/pdf/sbaa230
#
# Link for LM285 chip, connected to the ADS1256:
# https://www.ti.com/product/LM285-2.5-N
# https://www.ti.com/lit/gpn/lm285-2.5-n
#
# Link for DAC8532 chip:
# https://www.ti.com/product/DAC8532
# https://www.ti.com/lit/gpn/dac8532
#
# Spring City Solutions Links:
#
# Spring City Solutions Node-RED project page:
# https://www.springcitysolutions.com/nodered
#
# Spring City Solutions page for this node:
# https://www.springcitysolutions.com/nodered-waveshare-adda-shield
#
# Spring City Solutions Node-RED project email:
# nodered@springcitysolutions.com
#
# Spring City Solutions Gitlab for this node:
# https://gitlab.com/SpringCitySolutionsLLC/waveshare-shield-adda-11010
#
# Patreon Page:
# https://www.patreon.com/springcitysolutions_nodered
#
# Software Links:
#
# Spring City Solutions Gitlab for this node:
# https://gitlab.com/SpringCitySolutionsLLC/waveshare-shield-adda-11010
#
# Doxygen docs for this node autogenerated by Gitlab CI/CD:
# https://springcitysolutionsllc.gitlab.io/waveshare-shield-adda-11010/index.html
#
# npmjs for this node:
# https://npmjs.org/package/node-red-contrib-waveshare-shield-adda-11010
#
# Node-RED flows for this node:
# https://flows.nodered.org/node/node-red-contrib-waveshare-shield-adda-11010
#
# Documentation Links:
#
# Gitlab wiki for this node (the master copy of list of links is here):
# https://gitlab.com/SpringCitySolutionsLLC/waveshare-shield-adda-11010/-/wikis/home
#
# Waveshare's libraries for this hardware:
# https://github.com/waveshare/High-Precision-AD-DA-Board
#
# Youtube video "How to set up":
# TODO
#
# Youtube video "How to use":
# TODO
#
# Youtube video "Testing Results":
# TODO
#
# Usage:
#
# ads1256.py analog "channel number 0 to 7" "gain 1 to 64" "rate 2.5 to 30000" "on or off buffer" "sdcs off of current"
# returns 0 for 0 volts and decimal 0x7fffff for 5 volts
#
# ads1256.py calibrationFSC
# returns fullscale calibration register value as a decimal integer
#
# ads1256.py calibrationOFC
# returns offset calibration register value as a decimal integer
#
# ads1256.py digitalIn "D0 to D3"
# returns 0 or 1 as per input to the specified pin
#
# ads1256.py digitalOut "D0 to D3" "0 or 1"
 
import argparse
import json
import sys
 
import RPi.GPIO as GPIO
import spidev
 
# TODO: Could make the SPI control pins configurable.
cs = 22
drdy = 17
 
# The overall mode of operation
mode = 'analog'
# For GPIO
output = -1
 
register_address = dict([('status', 0x00),
                        ('mux', 0x01),
                        ('adcon', 0x02),
                        ('drate', 0x03),
                        ('gpio', 0x04),
                        ('ofc0', 0x05),
                        ('ofc1', 0x06),
                        ('ofc2', 0x07),
                        ('fsc0', 0x08),
                        ('fsc1', 0x09),
                        ('fsc2', 0x0a)])
 
register_data = dict([('adcon', 0x00),
                    ('drate', 0x00),
                    ('fsc', 0x000000),
                    ('gpio_direction_bitmask', 0x00),
                    ('gpio_status_bitmask', 0x00),
                    ("mux", 0x00),
                    ('ofc', 0x000000),
                    ('status', 0x00)])
 
 
# Functions that do things.
 
 
def output_json():
    """Prints a JSON of the register_data for development and testing."""
    print(json.dumps(register_data, sort_keys=True, indent=4))
 
 
def parse_args(raw_args):
    """Parses the args into ready to write register_data."""
    # First parse the CLI.
    parser = argparse.ArgumentParser()
    parser.add_argument("--mode", type=str, default="analog",
            help="Mode: analog, calibrationFSC, calibrationOFC, digitalIn, digitalOut default analog")
    parser.add_argument("--port_p", type=str, default="0",
            help="Positive Analog Input Port: 0 thru 8 default 0")
    parser.add_argument("--port_n", type=str, default="8",
            help="Negative Analog Input Port: 0 thru 8 default 8 (AINCOM)")
    parser.add_argument("--gain", type=str, default="1",
            help="Input Amp Gain: 1, 2, 4, 8, 16, 32, 64 default 1")
    parser.add_argument("--rate", type=str, default="2.5",
            help="Data Rate in samples per second: 2.5, 5, 10, 15, 25, 30, 50, 60, 100, 500, 1000, 2000, 3750, 7500, 15000, 30000 default 2.5")
    parser.add_argument("--buffer", type=str, default="off",
            help="Input Buffer: off, on default off")
    parser.add_argument("--sdcs", type=str, default="off",
            help="SDCS sensor direct current source microamps: off, 0.5, 2, 10 default off")
    parser.add_argument("--pin", type=str, default="D0",
            help="Specify pin for modes digitalIn and digitalOut: D0, D1, D2, D3 default D0")
    parser.add_argument("--output", type=str, default="-1",
            help="Absence means input mode, or specify output for modes digitalIn and digitalOut: 0, 1 default input mode")
    parser.add_argument("-t", "--test", action="store_true",
            help="Print JSON of register_data")
    args = parser.parse_args(raw_args)
 
    # Save global configs
    global mode
    mode = args.mode
    global output
    output = args.output
 
    # Process the STATUS register, including the BUFEN analog input buffer property.
    register_data['status'] = 0x00
    if (args.buffer == 'on'):
        register_data['status'] = 0x02
    if (args.buffer == 'off'):
        register_data['status'] = 0x00
 
    # Process the ADCON register, including PGA gain and SDCS property.
    register_data['adcon'] = 0x20  # Default clock out rate setting
    if (args.gain == '1'):
        register_data['adcon'] += 0x00
    if (args.gain == '2'):
        register_data['adcon'] += 0x01
    if (args.gain == '4'):
        register_data['adcon'] += 0x02
    if (args.gain == '8'):
        register_data['adcon'] += 0x03
    if (args.gain == '16'):
        register_data['adcon'] += 0x04
    if (args.gain == '32'):
        register_data['adcon'] += 0x05
    if (args.gain == '64'):
        register_data['adcon'] += 0x06
    if (args.sdcs == 'off'):
        register_data['adcon'] += 0x00
    if (args.sdcs == '0.5'):
        register_data['adcon'] += 0x08
    if (args.sdcs == '2'):
        register_data['adcon'] += 0x10
    if (args.sdcs == '10'):
        register_data['adcon'] += 0x18
 
    # Process the DRATE register, including the rate property.
    register_data['drate'] = 0x03
    if (args.rate == '30000'):
        register_data['drate'] = 0xF0
    if (args.rate == '15000'):
        register_data['drate'] = 0xE0
    if (args.rate == '7500'):
        register_data['drate'] = 0xD0
    if (args.rate == '3750'):
        register_data['drate'] = 0xC0
    if (args.rate == '2000'):
        register_data['drate'] = 0xB0
    if (args.rate == '1000'):
        register_data['drate'] = 0xA1
    if (args.rate == '500'):
        register_data['drate'] = 0x92
    if (args.rate == '100'):
        register_data['drate'] = 0x82
    if (args.rate == '60'):
        register_data['drate'] = 0x72
    if (args.rate == '50'):
        register_data['drate'] = 0x63
    if (args.rate == '30'):
        register_data['drate'] = 0x53
    if (args.rate == '25'):
        register_data['drate'] = 0x43
    if (args.rate == '15'):
        register_data['drate'] = 0x33
    if (args.rate == '10'):
        register_data['drate'] = 0x23
    if (args.rate == '5'):
        register_data['drate'] = 0x13
    if (args.rate == '2.5'):
        register_data['drate'] = 0x03
 
    # Process the MUX register, including the port.
    # register_data['mux'] = 0x08
    register_data['mux'] = (int(args.port_p) << 4) | int(args.port_n)
 
    # Process the gpio_direction_bitmask and gpio_status_bitmask registers, including the pin property.
    register_data['gpio_direction_bitmask'] = 0x10
    register_data['gpio_status_bitmask'] = 0x01
    if (args.pin == 'D0'):
        register_data['gpio_direction_bitmask'] = 0x10
        register_data['gpio_status_bitmask'] = 0x01
    if (args.pin == 'D1'):
        register_data['gpio_direction_bitmask'] = 0x20
        register_data['gpio_status_bitmask'] = 0x02
    if (args.pin == 'D2'):
        register_data['gpio_direction_bitmask'] = 0x40
        register_data['gpio_status_bitmask'] = 0x04
    if (args.pin == 'D3'):
        register_data['gpio_direction_bitmask'] = 0x80
        register_data['gpio_status_bitmask'] = 0x08
 
    # Optionally output register state for development purposes.
    if args.test:
        output_json()
        exit()
 
 
# Functions that read or write to the device.
# Device commands are run by functions named after the datasheet provided device command names.
# The datasheet names are all caps, Python names are lowercase, other than that issue, they match.
# The complete list of commands is on datasheet page 34 table 24.
 
 
def rreg(register):
    """Run RREG command as explained on datasheet page 36."""
    GPIO.output(cs, 0)
    firstbyte = 0x10 + register
    secondbyte = 0x01
    spi.writebytes([firstbyte, secondbyte])
    data = spi.readbytes(1)
    GPIO.output(cs, 1)
    return data[0]
 
 
def wreg(register, data):
    """Run WREG command as explained on datasheet page 36."""
    GPIO.output(cs, 0)
    firstbyte = 0x50 + register
    secondbyte = 0x01
    spi.writebytes([firstbyte, secondbyte, data])
    GPIO.output(cs, 1)
 
 
def selfcal():
    """Run SELFCAL command as explained on datasheet page 36."""
    GPIO.output(cs, 0)
    spi.writebytes([0xf0])
    GPIO.output(cs, 1)
    while True:
        if (GPIO.input(drdy) == 0):
            break
 
 
def rdata():
    """Run RDATA command as explained on datasheet page 34."""
    while True:
        if (GPIO.input(drdy) == 0):
            break
    GPIO.output(cs, 0)
    spi.writebytes([0x01])
    buf = spi.readbytes(3)
    GPIO.output(cs, 1)
    read = (buf[0] << 16) & 0xff0000
    read |= (buf[1] << 8) & 0xff00
    read |= (buf[2]) & 0xff
    return twos_complement_to_integer_24bit(read)
 
 
def sync():
    """Run SYNC command as explained on datasheet page 37."""
    GPIO.output(cs, 0)
    spi.writebytes([0xfc])
    GPIO.output(cs, 1)
 
 
def wakeup():
    """Run WAKEUP command as explained on datasheet page 37."""
    GPIO.output(cs, 0)
    spi.writebytes([0xff])
    GPIO.output(cs, 1)
 
 
def read_fsc_reg():
    """Read the FSC calibration value."""
    # See datasheet page 33 to read the raw byte values.
    # FSC per datasheet pg 24 is an unsigned 24 bit integer.
    register_data['fsc'] = 0x000000
    register_data['fsc'] += (rreg(register_address['fsc2']) << 16)
    register_data['fsc'] += (rreg(register_address['fsc1']) << 8)
    register_data['fsc'] += rreg(register_address['fsc0'])
 
 
def read_ofc_reg():
    """Read the OFC calibration value."""
    # See datasheet page 33 to read the raw byte values.
    # OFC per datasheet pg 24 is a twos complement 24 bit signed integer.
    ofc_twos_complement = 0x000000
    ofc_twos_complement += (rreg(register_address['ofc2']) << 16)
    ofc_twos_complement += (rreg(register_address['ofc1']) << 8)
    ofc_twos_complement += rreg(register_address['ofc0'])
    register_data['ofc'] = twos_complement_to_integer_24bit(ofc_twos_complement)
 
 
def write_adcon_reg():
    """Write the ADCON register.  See datasheet page 31."""
    wreg(register_address['adcon'], register_data['adcon'])
 
 
def write_drate_reg():
    """Write the DRATE register.  See datasheet page 32."""
    wreg(register_address['drate'], register_data['drate'])
 
 
def write_mux_reg():
    """Write the MUX register.  See datasheet page 31."""
    wreg(register_address['mux'], register_data['mux'])
 
 
def write_status_reg():
    """Write the STATUS register.  See datasheet page 30."""
    wreg(register_address['status'], register_data['status'])
 
 
# Functions that convert
 
 
def twos_complement_to_integer_24bit(twos_complement):
    """Convert a 24 bit twos complement value to a plain Python integer."""
    result = twos_complement
    if (twos_complement & (1 << 23)):
        result = twos_complement & ~(1 << 24)
        result = -(1 << 24) + result
    return result
 
 
parse_args(sys.argv[1:])
 
 
GPIO.setmode(GPIO.BCM)
GPIO.setwarnings(False)
GPIO.setup(cs, GPIO.OUT)
GPIO.output(cs, 1)
GPIO.setup(drdy, GPIO.IN)
 
spi = spidev.SpiDev()
spi.open(0, 0)
spi.max_speed_hz = 20000
spi.mode = 0b01
 
if (mode == 'analog'):
    # Write the registers in the correct order.
    write_status_reg()
    write_adcon_reg()
    write_drate_reg()
    write_mux_reg()
    # Self Calibration required after MUX change.
    selfcal()
    # Sync and Wakeup, in that order, are required to start a conversion.
    sync()
    wakeup()
    # Read data.
    print(rdata())
 
if (mode == 'calibrationFSC'):
    read_fsc_reg()
    print(register_data['fsc'])
 
if (mode == 'calibrationOFC'):
    read_ofc_reg()
    print(register_data['ofc'])
 
if (mode == 'digitalIn'):
    # Change exactly one bit to input mode.
    wreg(0x04, rreg(0x04) | register_data['gpio_direction_bitmask'])
    if ((rreg(0x04) & register_data['gpio_status_bitmask']) > 0):
        print('1')
    else:
        print('0')
 
if (mode == 'digitalOut'):
    if (output == '0'):
        wreg(0x04,
            rreg(0x04) & ~register_data['gpio_direction_bitmask'] & ~register_data['gpio_status_bitmask'])
    if (output == '1'):
        wreg(0x04,
            rreg(0x04) & ~register_data['gpio_direction_bitmask'] | register_data['gpio_status_bitmask'])