mcp2221a

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 6, 2020 License: MIT Imports: 6 Imported by: 1

README

GoDoc

mcp2221a

Go module for the MCP2221A USB to I²C/UART Protocol Converter with GPIO (datasheet)

Features

  • Fully-documented API
  • Compliant Go module (see below: Installation)
  • Supports multiple MCP2221A devices simultaneously
  • GPIO input/output
  • I²C read/write (configurable bit rate, up to 400 kHz)
  • ADC read (10-bit, 3 channels/pins), configurable reference voltage
  • DAC write (5-bit, 2 pins, shared output), configurable reference voltage and default output
  • Dedicated UART/I²C activity LED modes with configurable polarity
  • Rising/falling/both edge interrupt detection
  • Clock output on 1 pin (up to 12 MHz)
  • Save default/power-on configuration to flash memory (GPIO mode/value, DAC output, etc.)

Note that UART support is provided natively through the USB interface as a CDC device and is not handled by this module. It should show up in your OS as a regular TTY serial interface (/dev/tty* on Linux/macOS, COM on Windows).

Dependencies

Installation

If you are not using Go modules (or are unsure), just use the go built-in package manager:

go get -u -v github.com/ardnew/mcp2221a
Installation using modules

Either use the built-in package manager as above (and drop the -u):

go get -v github.com/ardnew/mcp2221a

Or simply add the import statement to your Go package's source code:

import (
  // ... other imports ...
  mcp "github.com/ardnew/mcp2221a"
)

The next time you run go build, the appropriate package will be downloaded automatically! Gee whiz!

Examples

See examples for some demo applications:

  • GPIO - classic "Blink" demo, toggles an LED connected to GPIO pin GP0
  • I²C - I²C address scanner, and also reads and prints the "Device ID" register contents from an INA260 power sensor
  • ADC - continuously reads and prints an analog value on GPIO pin GP1
  • DAC - continuously writes and prints an always-incrementing 5-bit value on GPIO pin GP2
  • Flash - prints the USB product descriptors from flash memory, and toggles power-up GPIO output value on pin GP0

Notes

GP operating modes

All of the available operating modes for the general-purpose (GP) pins:

  • GPIO: Operate as a digital input or a digital output pin.
  • SSPND: Reflects the USB state (Suspend/Resume); active-low when Suspend has been issued by the USB host, and driven high on Resume.
    • This lets the application react (e.g enter a low-power mode) when USB communication has been suspended or resumed.
    • The pin value can be inverted (high on Suspend, low on Resume) using the Flash module.
  • USBCFG: Starts out low during power-up/reset and goes high after successfully enumerating on the USB host.
    • The pin will also go low when in Suspend mode and high on Resume.
    • The pin value can be inverted (start high, low after enumeration) using the Flash module.
  • LED_URX,LED_UTX: Indicates UART (Rx/Tx) data being received/transmitted by pulsing the pin high for a few milliseconds.
    • The pin value can be inverted (pulse low on receive/transmit) using the Flash module.
  • LED_I2C: Indicates I²C (Rx and Tx) data being received and transmitted by pulsing the pin high for a few milliseconds.
    • The pin value can be inverted (pulse low on receive and transmit) using the Flash module.
  • CLKR: Digital output, providing a clock signal derived from the device’s internal clock.
    • The clock’s nominal frequency is 12 MHz ± 0.25%.
    • Other clock values and duty cycles can be configured using the Flash module.
  • IOC: Digital input ("Interrupt-on-Change") that is sensitive to rising, falling, or both edges.
    • The desired edge can be configured using the Flash and SRAM modules.
Supported modes

However, only certain pins support each of the operating modes listed above — per the following matrix yanked from the datasheet:

                  ╔══════════════╤══════════════╤══════════════╤══════════════╗
                  ║     GP0      │     GP1      │     GP2      │     GP3      ║
    ╔═════════════╬══════════════╪══════════════╪══════════════╪══════════════╣
    ║       GPIO  ║     GPIO     │     GPIO     │     GPIO     │     GPIO     ║
    ║  Dedicated  ║     SSPND    │     CLKR     │    USBCFG    │    LED_I2C   ║
    ║      Alt 1  ║    LED_URX   │     ADC1     │     ADC2     │     ADC3     ║
    ║      Alt 2  ║      --      │    LED_UTX   │     DAC1     │     DAC2     ║
    ║      Alt 3  ║      --      │     IOC      │      --      │      --      ║
    ╚═════════════╩══════════════╧══════════════╧══════════════╧══════════════╝
Datasheet

Please refer to this before sending me a confusing question:

To get started reading this thing, and easier grokking, note that:

  • The first half of the datasheet (.pdf) defines internal registers and inter-component behaviors which are all but completely transparent to us. This info can be ignored, but be sure to read the front-matter and any component descriptions.
  • The second half of the datasheet (.pdf) defines the USB HID command and response formats. This is the good stuff that pertains to developers of or using this Go module.
Where to get one

Adafruit makes a crazy cheap, snazzy breakout with built-in 3.3V regulator (with VBUS/5V and 3.3V output pins), an I²C Qwiic/Stemma QT connector (as well as the regular SDA/SCL pins), and best of all a USB-C connector as its programming interface:

Documentation

Overview

Package mcp2221a provides a high-level interface to the Microchip MCP2221A USB to GPIO/I²C/UART protocol converter. The physical GPIO and I²C modules are implemented as USB HID-class devices, while the UART module is USB CDC. This package only supports the USB HID-class devices (GPIO/I²C) and all of the functions associated with them (ADC, DAC, SRAM, and flash memory).

Datasheet: http://ww1.microchip.com/downloads/en/devicedoc/20005565b.pdf

Index

Constants

View Source 
const (
	VersionPkg = "mcp2221a"
	VersionMaj = 0
	VersionMin = 1
	VersionPch = 1
)

Constants associated with package version.

View Source 
const (
	VID = 0x04D8 // 16-bit vendor ID for Microchip Technology Inc.
	PID = 0x00DD // 16-bit product ID for the Microchip MCP2221A.
)

VID and PID are the official vendor and product identifiers assigned by the USB-IF.

View Source 
const (
	WordSet byte = 0xFF // All bits set
	WordClr byte = 0x00 // All bits clear
)

WordSet and WordClr are the logical true and false values for a single word (byte) in a message.

View Source 
const (
	// GPPinCount is the number of GPIO pins available.
	GPPinCount = 4

	// GPIO operation modes:         GP0       GP1       GP2      GP3
	ModeGPIO     GPIOMode = 0x00 //  GPIO      GPIO      GPIO     GPIO
	ModeDediFunc GPIOMode = 0x01 //  SSPND     CLKR      USBCFG   LED_I2C
	ModeAltFunc0 GPIOMode = 0x02 //  LED_URX   ADC1      ADC2     ADC3
	ModeAltFunc1 GPIOMode = 0x03 //  --        LED_UTX   DAC1     DAC2
	ModeAltFunc2 GPIOMode = 0x04 //  --        IOC       --       --
	ModeInvalid  GPIOMode = 0xEE // invalid mode is used as error condition

	// General GPIO functions
	ModeADC       = ModeAltFunc0
	ModeDAC       = ModeAltFunc1
	ModeInterrupt = ModeAltFunc2

	// Special functions
	ModeSSPND  = ModeDediFunc
	ModeCLKOUT = ModeDediFunc
	ModeUSBCFG = ModeDediFunc

	// LED status functions
	ModeLEDI2C = ModeDediFunc
	ModeLEDURx = ModeAltFunc0
	ModeLEDUTx = ModeAltFunc1

	// GPIO directions
	DirOutput  GPIODir = 0x00 // direction OUT is used for writing values to pins
	DirInput   GPIODir = 0x01 // direction IN is used for reading values from pins
	DirInvalid GPIODir = 0xEF // invalid direction is used as error condition
)

Constants associated with the GPIO module.

View Source 
const (
	I2CBaudRate = 100000 // default baud rate
	I2CMinAddr  = 0x08   // minimum possible 7-bit address
	I2CMaxAddr  = 0x77   // maximum possible (unreserved) 7-bit address
)

Constants associated with the I²C module.

View Source 
const ClkHz = 12000000

ClkHz is the internal clock frequency of the MCP2221A.

View Source 
const MsgSz = 64

MsgSz is the size (in bytes) of all command and response messages.

Variables

This section is empty.

Functions

func AttachedDevices 

func AttachedDevices(vid uint16, pid uint16) []usb.DeviceInfo

AttachedDevices returns a slice of all connected USB HID device descriptors matching the given VID and PID.

Returns an empty slice if no devices were found. See the hid package documentation for details on inspecting the returned objects.

func PackageVersion 

func PackageVersion() string

PackageVersion returns the descriptive version string of this package.

func Version 

func Version() string

Version returns the SemVer-compatible version string of this package.

Types

type ADC 

type ADC struct {
	*MCP2221A
}

ADC contains the methods associated with the ADC module of the MCP2221A.

func (*ADC) FlashConfig 

func (mod *ADC) FlashConfig(pin byte, ref VRef) error

FlashConfig configures the analog-to-digital converter by setting the given pin's operation mode to ADC, the ADC reference voltage to ref, and then writes these settings to flash memory. These settings become default and are retained after next startup/reset.

Returns an error if the receiver is invalid, pin does not have an associated ADC channel, ref is invalid, or if the new configuration could not be sent.

func (*ADC) GetConfig 

func (mod *ADC) GetConfig(pin byte) (VRef, error)

GetConfig reads the current ADC configuration for the given pin, returning the ADC reference voltage.

Returns VRefDefault reference voltage and an error if the receiver is invalid, pin is invalid, or if the current configuration could not be read.

func (*ADC) Read 

func (mod *ADC) Read(pin byte) (uint16, error)

Read performs an analog-to-digital conversion reading on the given pin and returns the value.

Returns the converted analog value as an unsigned 16-bit integer. Returns an error if the receiver is invalid, VRef is invalid, or if the new configuration could not be sent.

func (*ADC) SetConfig 

func (mod *ADC) SetConfig(pin byte, ref VRef) error

SetConfig configures the analog-to-digital converter by setting the given pin's operation mode to ADC and the ADC reference voltage to ref. These settings only affect the current device configuration and are not retained after next startup/reset (see: FlashConfig()).

Returns an error if the receiver is invalid, pin does not have an associated ADC channel, ref is invalid, or if the new configuration could not be sent.

type ChipSecurity 

type ChipSecurity byte

ChipSecurity holds one of the enumerated security configuration constants. 

const (
	SecUnsecured ChipSecurity = 0x00
	SecPassword  ChipSecurity = 0x01
	SecLocked1   ChipSecurity = 0x10 // equivalent to SecLocked2
	SecLocked2   ChipSecurity = 0x11 // equivalent to SecLocked1
)

Constants related to ChipSecurity.

type DAC 

type DAC struct {
	*MCP2221A
}

DAC contains the methods associated with the DAC module of the MCP2221A.

func (*DAC) FlashConfig 

func (mod *DAC) FlashConfig(pin byte, ref VRef, val byte) error

FlashConfig configures the digital-to-analog converter by setting the given pin's operation mode to DAC, the DAC reference voltage to ref, the default startup output value to val, and then writes these settings to flash memory. These settings become default and are retained after next startup/reset.

Returns an error if the receiver is invalid, pin does not have an associated DAC output, ref is invalid, or if the new configuration could not be sent.

func (*DAC) GetConfig 

func (mod *DAC) GetConfig(pin byte) (byte, VRef, error)

GetConfig reads the current DAC configuration for the given pin, returning the power-up DAC value and reference voltage.

Returns WordClr power-up value, VRefDefault reference voltage, and an error if the receiver is invalid, pin is invalid or is not configured for DAC operation, or if the current configuration could not be read.

func (*DAC) SetConfig 

func (mod *DAC) SetConfig(pin byte, ref VRef) error

SetConfig configures the digital-to-analog converter by setting the given pin's operation mode to DAC and the DAC reference voltage to ref. These settings only affect the current device configuration and are not retained after next startup/reset (see: FlashConfig()).

Returns an error if the receiver is invalid, pin does not have an associated DAC output, ref is invalid, or if the new configuration could not be sent.

func (*DAC) Write 

func (mod *DAC) Write(val uint16) error

Write performs a digital-to-analog conversion and outputs the given value on all DAC-enabled pins. The device only has a single DAC with two pins connected to it, so the value output will be present on both pins if they are both configured for DAC operation.

Returns an error if the receiver is invalid or if the converted value could not be sent.

type Flash 

type Flash struct {
	*MCP2221A
}

Flash contains the methods associated with the flash memory component of the MCP2221A.

func (*Flash) FactorySerialNo 

func (mod *Flash) FactorySerialNo() (string, error)

FactorySerialNo reads the factory serial number (read-only) from flash memory and returns it as a string.

Returns an empty string and error if the receiver is invalid or if the flash configuration could not be read.

func (*Flash) USBManufacturer 

func (mod *Flash) USBManufacturer() (string, error)

USBManufacturer reads the current USB manufacturer description from flash memory and returns it as a string.

Returns an empty string and error if the receiver is invalid or if the flash configuration could not be read.

func (*Flash) USBProduct 

func (mod *Flash) USBProduct() (string, error)

USBProduct reads the current USB product description from flash memory and returns it as a string.

Returns an empty string and error if the receiver is invalid or if the flash configuration could not be read.

func (*Flash) USBSerialNo 

func (mod *Flash) USBSerialNo() (string, error)

USBSerialNo reads the current USB serial number from flash memory and returns it as a string.

Returns an empty string and error if the receiver is invalid or if the flash configuration could not be read.

type GPIO 

type GPIO struct {
	*MCP2221A
}

GPIO contains the methods associated with the GPIO module of the MCP2221A.

func (*GPIO) FlashConfig 

func (mod *GPIO) FlashConfig(pin byte, val byte, mode GPIOMode, dir GPIODir) error

FlashConfig configures a given pin with a default output value, operation mode, direction, and then writes that configuration to flash memory. These settings become default and are retained after next startup/reset.

Returns an error if the receiver is invalid, the pin index is invalid, the current configuration could not be read, or if the new configuration could not be sent.

func (*GPIO) Get 

func (mod *GPIO) Get(pin byte) (byte, error)

Get gets the current digital value of a given pin.

Returns an error if the receiver is invalid, the pin index is invalid, or if the pin value could not be set (e.g. pin not configured for GPIO operation).

func (*GPIO) GetConfig 

func (mod *GPIO) GetConfig(pin byte) (byte, GPIOMode, GPIODir, error)

GetConfig reads the current default output value, operation mode, and direction of a given pin.

Returns an error if the receiver is invalid, the pin index is invalid, or if the current configuration could not be read.

func (*GPIO) Set 

func (mod *GPIO) Set(pin byte, val byte) error

Set sets the digital output value for a given pin.

Returns an error if the receiver is invalid, the pin index is invalid, or if the pin value could not be set (e.g. pin not configured for GPIO operation).

func (*GPIO) SetConfig 

func (mod *GPIO) SetConfig(pin byte, val byte, mode GPIOMode, dir GPIODir) error

SetConfig configures a given pin with a default output value, operation mode, and direction. These settings only affect the current device configuration and are not retained after next startup/reset (see: FlashConfig()).

Returns an error if the receiver is invalid, the pin index is invalid, the current configuration could not be read, or if the new configuration could not be sent.

type GPIODir 

type GPIODir byte

GPIOMode and GPIODir represent two of the configuration parameters for all of the general purpose (GP) pins.

type GPIOMode 

type GPIOMode byte

GPIOMode and GPIODir represent two of the configuration parameters for all of the general purpose (GP) pins.

type I2C 

type I2C struct {
	*MCP2221A
}

I2C contains the methods associated with the I²C module of the MCP2221A.

func (*I2C) Cancel 

func (mod *I2C) Cancel() error

Cancel sends a set-parameters command to cancel any ongoing I²C transfer currently in progress.

Returns an error if the receiver is invalid, or if the command could not be sent.

func (*I2C) Read 

func (mod *I2C) Read(rep bool, addr uint8, cnt uint16) ([]byte, error)

Read is the general purpose function for reading raw data directly from the I²C data bus. If argument rep is true, a REP-START condition is generated (instead of the usual START condition) to indicate we are reading data from a slave subaddress configured before this call to Read().

Returns the data slice of length cnt (bytes) read from the bus if there was no error. Otherwise, an error is returned if any of the following occur: invalid receiver, could not read status message, could not cancel an existing I²C connection (if exists), could not send command message, the I²C state machine enters an unrecoverable state.

func (*I2C) ReadReady 

func (mod *I2C) ReadReady() (bool, error)

ReadReady tests if the device needs to perform a read from a requested slave device.

Returns false and an error if the receiver is invalid or if the I²C state machine status could not be read.

func (*I2C) ReadReg 

func (mod *I2C) ReadReg(addr uint8, reg uint8, cnt uint16) ([]byte, error)

ReadReg performs a standard write-then-read I²C operation as a convenience for the common case of reading registers. This variant is for target devices with 8-bit subaddress widths (i.e. the size of the register pointer).

Returns the bytes received on success, or return error if either write or read failures occurred.

See also I2CReadReg16() for 16-bit subaddressing devices.

func (*I2C) ReadReg16 

func (mod *I2C) ReadReg16(addr uint8, reg uint16, msb bool, cnt uint16) ([]byte, error)

ReadReg16 performs a standard write-then-read I²C operation as a convenience for the common case of reading registers. This variant is for target devices with 16-bit subaddress widths (i.e. the size of the register pointer). If argument msb is true, then the buffer containing the register pointer is reversed so that the MSByte is at buffer index 0.

Returns the bytes received on success, or returns an error if either write or read failures occurred.

See also I2CReadReg() for 8-bit subaddressing devices.

func (*I2C) Scan 

func (mod *I2C) Scan(start uint8, stop uint8) ([]uint8, error)

Scan scans a given address range and attempts to communicate with each device, ignoring any failures caused by non-existent targets.

Returns a byte slice of 7-bit addresses known to be online and able to be communicated with. Returns a nil slice and error if the receiver is invalid or given address range is invalid.

func (*I2C) SetConfig 

func (mod *I2C) SetConfig(baud uint32) error

SetConfig configures the I²C bus clock divider calculated from a given baud rate (BPS). If in doubt, use global constant I2CBaudRate. These settings only affect the current device configuration and are not retained after next startup/reset.

Returns an error if the receiver is invalid, the given baud rate is invalid, the set-parameters command could not be sent, or if an I²C transfer is currently in-progress.

func (*I2C) Write 

func (mod *I2C) Write(stop bool, addr uint8, out []byte, cnt uint16) error

Write is the general-purpose function for writing raw data directly to the I²C data bus. If argument stop is true, then an I²C STOP condition is generated on the bus once the bytes transmitted equals the number bytes specified as parameter cnt (this is the "usual" case). Otherwise, the STOP condition is not generated, and the bus remains "active" for subsequent I/O.

Returns an error if any of the following occur: invalid receiver, could not read status message, could not cancel an existing I²C connection (if exists), could not send command message, the I²C state machine enters an unrecoverable state, or too many retries were attempted.

type IOC 

type IOC struct {
	*MCP2221A
}

IOC contains the methods associated with the IOC module of the MCP2221A.

func (*IOC) FlashConfig 

func (mod *IOC) FlashConfig(edge IOCEdge) error

FlashConfig configures the sole interrupt-capable GPIO pin's operation mode for interrupt detection, sets the edge detection to the given edge, and then writes these settings to flash memory. Note the interrupt flag is not cleared as it is with SetConfig(). These settings become default and are retained after next startup/reset.

Returns an error if the receiver is invalid, the pin's operation mode could not be set, the edge configuration could not be set, or if the interrupt flag could not be cleared.

func (*IOC) GetConfig 

func (mod *IOC) GetConfig() (IOCEdge, error)

GetConfig returns the selected detection edge configured for the interrupt detection module.

Returns DisableIOC detection edge and an error if the receiver is invalid or if the current configuration could not be read.

func (*IOC) SetConfig 

func (mod *IOC) SetConfig(edge IOCEdge) error

SetConfig configures the sole interrupt-capable GPIO pin's operation mode for interrupt detection, sets the edge detection to the given edge, and clears the current interrupt flag. These settings only affect the current device configuration and are not retained after next startup/reset (see: FlashConfig()).

Returns an error if the receiver is invalid, the pin's operation mode could not be set, the edge configuration could not be set, or if the interrupt flag could not be cleared.

type IOCEdge 

type IOCEdge byte

IOCEdge represents the edge which triggers an interrupt. 

const (
	DisableIOC        IOCEdge = 0x00
	RisingEdge        IOCEdge = 0x01
	FallingEdge       IOCEdge = 0x02
	RisingFallingEdge IOCEdge = 0x03
)

Constants associated with the interrupt detection module (IOC).

type MCP2221A 

type MCP2221A struct {
	Device *usb.Device
	Index  byte
	VID    uint16
	PID    uint16

	// each of the on-chip modules acting as primary functional interfaces.
	SRAM  *SRAM  // volatile active settings, not restored on startup/reset
	Flash *Flash // non-volatile inactive settings, restored on startup/reset
	GPIO  *GPIO  // 4x GPIO pins, each also have unique special functions
	ADC   *ADC   // 3x 10-bit analog-to-digital converter
	DAC   *DAC   // 1x 5-bit digital-to-analog converter (avail on 2 pins)
	IOC   *IOC   // input interrupt detection (used with SSPND)
	I2C   *I2C   // dedicated I²C SDA/SCL pins, up to 400 kHz
}

MCP2221A is the primary object used for interacting with the device and all of its modules. The struct contains a pointer to an opened HIDAPI device through which all USB communication occurs. However, the HIDAPI device should not be used directly, as communication should be performed through one of the respective on-chip modules. If multiple MCP2221A devices are connected to the host PC, the index of the desired target can be determined with AttachedDevices() and passed to New(). An index of 0 will use the first device found. Pointers to structs representing each of the chip's modules are exported for interacting with that component of the device. Call Close() on the device when finished to also close the USB connection.

func New 

func New(idx byte, vid uint16, pid uint16) (*MCP2221A, error)

New returns a new MCP2221A object with the given VID and PID, enumerated at the given index (an index of 0 will use the first device found).

Returns an error if index is out of range (according to AttachedDevices()) or if the USB HID device could not be claimed or opened.

func (*MCP2221A) Close 

func (mcp *MCP2221A) Close() error

Close will clean up any resources and close the USB HID connection.

Returns an error if the USB HID device is invalid or failed to close gracefully.

func (*MCP2221A) Reset 

func (mcp *MCP2221A) Reset(timeout time.Duration) error

Reset sends a reset command and then attempts to reopen a connection to the same USB HID device within a given timeout duration.

Returns an error if the receiver is invalid, the reset command could not be sent, or if the device could not be reopened before the given timeout period.

type Polarity 

type Polarity bool

Polarity represents the digital state of certain pins/bits in the flash settings struct.

type SRAM 

type SRAM struct {
	*MCP2221A
}

SRAM contains the methods associated with the SRAM component of the MCP2221A.

type VRef 

type VRef byte

VRef represents one of the enumerated constants that can be used as reference voltage for both the ADC and DAC modules. 

const (
	VRefDefault VRef = 0x00 // Default (Vdd)
	VRefVdd     VRef = 0x00 // Vdd
	VRef4p096   VRef = 0x07 // 4.096 V
	VRef2p048   VRef = 0x05 // 2.048 V
	VRef1p024   VRef = 0x03 // 1.024 V
	VRefOff     VRef = 0x01 // reference voltage disabled
)

Constants for enumerated reference voltage values used by the settings structure read from and written to SRAM and flash.

Source Files

View all Source files

Directories

Path Synopsis
examples
adc
dac
flash
gpio
i2c

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.