Add support for MCP3004, MCP3204 and MCP3208

The MCP3004 and MCP3008 have almost identical implementation, as well as
the MCP3204 and MCP3208. Although differences between MCP3004/8 vs
MCP3204/8 are small, it was hard to come up with a shared abstraction
that wasn't very hard to read and understant. Therefore I wrote 2
implementations which lead to some duplicate code.

Author: OrangeTux

README.md

@@ -2,7 +2,7 @@
 
 Go packages for pheripheral I/O.
 
-    * [spi][spi]
+* [spi][spi]
 
 ## License
 

spi/adc/README.md

@@ -1,3 +1,5 @@
+[![godoc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/AdvancedClimateSystems/io/spi/adc)
+
 # ADC
 
 Package ADC implements a few Analog Digital Converters (ADC). Communication
@@ -20,7 +22,7 @@ func main() {
 	conn, err := spi.Open(&spi.Devfs{
 		Dev:      "/dev/spidev32766.0",
 		Mode:     spi.Mode0,
-		MaxSpeed: 5000000,
+		MaxSpeed: 3600000,
 	})
 
 	if err != nil {
@@ -42,7 +44,9 @@ func main() {
 	fmt.Printf("read %f Volts from channel 3", v)
 }
 ```
-
 ## Supported ADC's
 
-* MCP3008
+* [MCP3004](http://www.microchip.com/wwwproducts/en/MCP3004)
+* [MCP3008](http://www.microchip.com/wwwproducts/en/MCP3008)
+* [MCP3204](http://www.microchip.com/wwwproducts/en/MCP3204)
+* [MCP3208](http://www.microchip.com/wwwproducts/en/MCP3208)

spi/adc/adc.go

@@ -10,7 +10,7 @@ import (
 )
 
 // InputType defines how an ADC samples the input signal. A single-ended input
-// samples its input in the range from the ground (0V) to Vref, or the refence
+// samples its input in the range from the ground (0V) to Vref, that is  the reference
 // input. A 10-bits ADC with a reference input of 5V has a precision of (5 -
 // 0) / 1024 = 0.0049V = 4.9mV on single-ended inputs.
 //
@@ -24,18 +24,45 @@ type InputType int
 const (
 	// SingleEnded configures the inputs of an ADC as single-ended.
 	SingleEnded InputType = 0
+
 	// PseudoDifferential configures the inputs of an ADC as pseudo-differential.
 	PseudoDifferential InputType = 1
 )
 
 // ADC is the interface that wraps a Read method.
 //
-// Read returns the voltage of a channel of the ADC.
+// Read queries the channel of an ADC and returns it's voltage.
 type ADC interface {
 	Read(channel int) (float64, error)
 }
 
+// MCP3004 is 10-bits ADC with 4 single-ended or 2 pseudo-differential inputs.
+// Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/21295C.pdf
+type MCP3004 struct {
+	Conn *spi.Device
+
+	// Vref is the voltage on the reference input of the ADC.
+	Vref float64
+
+	InputType InputType
+}
+
+// Read returns the voltage of a channel.
+func (m MCP3004) Read(channel int) (float64, error) {
+	if channel < 0 || channel > 4 {
+		return 0, fmt.Errorf("channel %d is invalid, ADC has only 4 channels", channel)
+	}
+
+	raw, err := read10(m.Conn, channel, m.InputType)
+	if err != nil {
+		return 0, err
+	}
+
+	return (m.Vref / 1024) * float64(raw), nil
+}
+
 // MCP3008 is 10-bits ADC with 8 single-ended or 4 pseudo-differential inputs.
+// Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/21295C.pdf
 type MCP3008 struct {
 	Conn *spi.Device
 
@@ -47,12 +74,26 @@ type MCP3008 struct {
 
 // Read returns the voltage of a channel.
 func (m MCP3008) Read(channel int) (float64, error) {
+	if channel < 0 || channel > 7 {
+		return 0, fmt.Errorf("channel %d is invalid, ADC has only 8 channels", channel)
+	}
+
+	raw, err := read10(m.Conn, channel, m.InputType)
+	if err != nil {
+		return 0, err
+	}
+
+	return (m.Vref / 1024) * float64(raw), nil
+}
+
+// read10 reads a 10 bits value from an channel of an ADC.
+func read10(conn *spi.Device, channel int, inputType InputType) (int, error) {
 	var cmd int
 
 	// The first bit after the start bit will determine if the conversion
 	// is done using single-ended or differential input mode. 0 means
 	// differential, 1 means single-ended.
-	if m.InputType == SingleEnded {
+	if inputType == SingleEnded {
 		cmd = 1
 	}
 	// The bit is then shifted 3 times and the number is incremented with
@@ -77,7 +118,7 @@ func (m MCP3008) Read(channel int) (float64, error) {
 	// bytes we read 3 bytes.
 	in := make([]byte, 3)
 
-	if err := m.Conn.Tx(out, in); err != nil {
+	if err := conn.Tx(out, in); err != nil {
 		return 0, fmt.Errorf("failed to read channel %d: %v", channel, err)
 	}
 
@@ -100,7 +141,113 @@ func (m MCP3008) Read(channel int) (float64, error) {
 	// 00000010 10110111
 	//
 	// 00000010 10110111 is 696 in base10.
-	output := float64(int(in[1]&3)<<8 + int(in[2]))
+	return int(in[1]&3)<<8 + int(in[2]), nil
+}
+
+// MCP3204 is 12-bits ADC with 4 single-ended or 2 pseudo-differential inputs.
+// Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/21298e.pdf
+type MCP3204 struct {
+	Conn *spi.Device
 
-	return (m.Vref / 1024) * output, nil
+	// Vref is the voltage on the reference input of the ADC.
+	Vref float64
+
+	InputType InputType
+}
+
+// Read returns the voltage of a channel.
+func (m MCP3204) Read(channel int) (float64, error) {
+	if channel < 0 || channel > 4 {
+		return 0, fmt.Errorf("channel %d is invalid, ADC has only 4 channels", channel)
+	}
+
+	raw, err := read12(m.Conn, channel, m.InputType)
+	if err != nil {
+		return 0, err
+	}
+
+	return (m.Vref / 4096) * float64(raw), nil
+}
+
+// MCP3208 is 12-bits ADC with 8 single-ended or 4 pseudo-differential inputs.
+// Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/21298e.pdf
+type MCP3208 struct {
+	Conn *spi.Device
+
+	// Vref is the voltage on the reference input of the ADC.
+	Vref float64
+
+	InputType InputType
+}
+
+// Read returns the voltage of a channel.
+func (m MCP3208) Read(channel int) (float64, error) {
+	if channel < 0 || channel > 8 {
+		return 0, fmt.Errorf("channel %d is invalid, ADC has only 8 channels", channel)
+	}
+
+	raw, err := read12(m.Conn, channel, m.InputType)
+	if err != nil {
+		return 0, err
+	}
+
+	return (m.Vref / 4096) * float64(raw), nil
+}
+
+// read12 reads a 12 bits value from an channel of an ADC.
+func read12(conn *spi.Device, channel int, inputType InputType) (int, error) {
+	// The start bit.
+	cmd := 1
+	cmd = cmd << 1
+
+	// The first bit after the start bit will determine if the conversion
+	// is done using single-ended or differential input mode. 0 means
+	// differential, 1 means single-ended.
+	if inputType == SingleEnded {
+		cmd = 1
+	}
+	// The bit is then shifted 3 times and the number is incremented with
+	// a 3 bits channel.
+	cmd = cmd << 3
+	cmd += channel
+
+	// The result is shifted 6 times.
+	//
+	// x x x x x 1 1 1   1 1 x x x x x x
+	//           | | |   | | ------- 3 bits for selecting channel
+	//	     | |---------------- 1 bit defining single-ended or pseudo-differential input mode
+	//	     |------------------ 1 start bit
+	cmd = cmd << 6
+
+	// The data is is in the first 2 bytes, the third byte is an empty byte.
+	out := []byte{byte(cmd >> 8), byte(cmd & 0xFF), 0}
+
+	// For every byte send the SPI master reads a byte. Because we send 3
+	// bytes we read 3 bytes.
+	in := make([]byte, 3)
+
+	if err := conn.Tx(out, in); err != nil {
+		return 0, fmt.Errorf("failed to read channel %d: %v", channel, err)
+	}
+
+	// The 12-bits measurement is at the end of the 3 byte response.
+	//
+	// 11111111 11101100 10110111
+	//              ^^^^ ^^^^^^^^
+	// To get the base10 value of the channel the second byte is masked
+	// with 15:
+	//
+	//	    11101100
+	//          00001111
+	//          -------- &
+	//          00001100
+	//
+	// The byte is shifted 8 bits and the last byte is added:
+	// 00001100 00000000
+	//          10110111
+	//          -------- +
+	// 00001100 10110111
+	//
+	// 00001100 10110111 is 3255 in base10.
+	return int(in[1]&0xF)<<8 + int(in[2]), nil
 }

spi/adc/adc_test.go

@@ -30,7 +30,7 @@ func (c testConn) Tx(w, r []byte) error {
 }
 func (c testConn) Close() error { return nil }
 
-func TestMCP3008(t *testing.T) {
+func TestMCP300x(t *testing.T) {
 	var tests = []struct {
 		resp []byte
 		v    float64
@@ -44,7 +44,7 @@ func TestMCP3008(t *testing.T) {
 	for _, test := range tests {
 		c := testConn{
 			tx: func(w, r []byte) error {
-				assert.Equal(t, []byte{1, 240, 0}, w)
+				assert.Equal(t, []byte{1, 176, 0}, w)
 
 				r[1] = test.resp[0]
 				r[2] = test.resp[1]
@@ -54,14 +54,69 @@ func TestMCP3008(t *testing.T) {
 		}
 
 		con, _ := spi.Open(&testDriver{c})
-		m := MCP3008{
+		mcp3004 := MCP3004{
 			Conn:      con,
 			Vref:      5.0,
 			InputType: SingleEnded,
 		}
 
-		v, _ := m.Read(7)
+		v, _ := mcp3004.Read(3)
 		assert.Equal(t, test.v, v)
+
+		mcp3008 := MCP3008{
+			Conn:      con,
+			Vref:      5.0,
+			InputType: SingleEnded,
+		}
+
+		v, _ = mcp3008.Read(3)
+		assert.Equal(t, test.v, v)
+	}
+}
+
+func TestMCP320x(t *testing.T) {
+	var tests = []struct {
+		resp []byte
+		v    float64
+	}{
+		{[]byte{0, 0}, 0},
+		{[]byte{2, 0}, 0.625},
+		{[]byte{6, 0}, 1.875},
+		{[]byte{1, 13}, 0.328369140625},
+		{[]byte{255, 255}, 4.998779296875},
+	}
+
+	for _, test := range tests {
+		c := testConn{
+			tx: func(w, r []byte) error {
+				assert.Equal(t, []byte{4, 192, 0}, w)
+
+				r[1] = test.resp[0]
+				r[2] = test.resp[1]
+
+				return nil
+			},
+		}
+
+		con, _ := spi.Open(&testDriver{c})
+		mcp3204 := MCP3204{
+			Conn:      con,
+			Vref:      5.0,
+			InputType: PseudoDifferential,
+		}
+
+		v, _ := mcp3204.Read(3)
+		assert.Equal(t, test.v, v)
+
+		mcp3208 := MCP3208{
+			Conn:      con,
+			Vref:      5.0,
+			InputType: PseudoDifferential,
+		}
+
+		v, _ = mcp3208.Read(3)
+		assert.Equal(t, test.v, v)
+
 	}
 }
 
@@ -81,6 +136,9 @@ func ExampleMCP3008() {
 	a := MCP3008{
 		Conn: conn,
 		Vref: 5.0,
+
+		// Optional, default value is SingleEnded.
+		InputType: PseudoDifferential,
 	}
 
 	// Read the voltage on channel 3.