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
- func AttachedDevices(vid uint16, pid uint16) []usb.DeviceInfo
- func PackageVersion() string
- func Version() string
- type ADC
- type ChipSecurity
- type DAC
- type Flash
- type GPIO
- func (mod *GPIO) FlashConfig(pin byte, val byte, mode GPIOMode, dir GPIODir) error
- func (mod *GPIO) Get(pin byte) (byte, error)
- func (mod *GPIO) GetConfig(pin byte) (byte, GPIOMode, GPIODir, error)
- func (mod *GPIO) Set(pin byte, val byte) error
- func (mod *GPIO) SetConfig(pin byte, val byte, mode GPIOMode, dir GPIODir) error
- type GPIODir
- type GPIOMode
- type I2C
- func (mod *I2C) Cancel() error
- func (mod *I2C) Read(rep bool, addr uint8, cnt uint16) ([]byte, error)
- func (mod *I2C) ReadReady() (bool, error)
- func (mod *I2C) ReadReg(addr uint8, reg uint8, cnt uint16) ([]byte, error)
- func (mod *I2C) ReadReg16(addr uint8, reg uint16, msb bool, cnt uint16) ([]byte, error)
- func (mod *I2C) Scan(start uint8, stop uint8) ([]uint8, error)
- func (mod *I2C) SetConfig(baud uint32) error
- func (mod *I2C) Write(stop bool, addr uint8, out []byte, cnt uint16) error
- type IOC
- type IOCEdge
- type MCP2221A
- type Polarity
- type SRAM
- type VRef
Constants ¶
const ( VersionPkg = "mcp2221a" VersionMaj = 0 VersionMin = 1 VersionPch = 1 )
Constants associated with package version.
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.
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.
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.
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.
const ClkHz = 12000000
ClkHz is the internal clock frequency of the MCP2221A.
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.
Types ¶
type ADC ¶
type ADC struct {
*MCP2221A
}
ADC contains the methods associated with the ADC module of the MCP2221A.
func (*ADC) FlashConfig ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 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 ¶
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 ¶
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 ¶
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.