drbild / cp2130

Python library for the Silicon Labs CP2130 USB to SPI Bridge

cp2130

This module provides a Python SDK for the Silicon Labs CP2130 USB to SPI Bridge integrated circuit. It exposes a Pythonic API for accessing the one-time programmable ROM, device state, GPIOs, and SPI slave devices.

Installation

pip install cp2130

The package is published to PyPI for Python 2.7 and 3.3+. pip installs all dependencies.

Dependencies

The PyUSB or python-libusb1 libraries is used to access the USB device. If neither PyUSB nor python-libusb1 is available for your platform, a different USB library may be used by implementing the cp2130.usb.USBDevice interface. See cp2130/usb/pyusb.py and cp2130/usb/libusb1.py as an examples.

Quick-Start

The following python script illustrates basic usage of the Pythonic API. See the CP2130 Interface Specification for full details of the capabilities of the chip. All features are exposed by the API, but not all are demonstrated in this README.

import cp2130
from cp2130.data import *

# If the vendor or product ids are not the default, use
# the form cp2130.find(vid=0xXXXX, pid=0xXXXX).
chip = cp2130.find() 

#######################################################
# SPI Reads/Writes
#######################################################
slave = chip.channel0

# Print a summary of the channel state
print slave

# Write 4 bytes of data to the slave
command = b'\x01\x02\x03\0x04'
slave.write(command)

# Read 8 bytes of data
response = slave.read(8)

# Issue a two-part transaction
part1 = b'\x01\x02'
part2 = b'\x03\x04'
slave.write(part1, cs_hold=True) # Keeps CS asserted
slave.write(part2)

# NOTE: cs_hold is not supported by the CP2130 native chip-select 
# capabilities. To use cs_hold, configure the chip select line as
# a GPIO instead of a chip select. This library will then manually
# manage the chip select state. I.e,:
#   chip.pin_config.gpio0.function = OutputMode.PUSH_PULL # or OutputMode.OPEN_DRAIN
# instead of
#   chip.pin_config.gpio0.function = GPIO0Mode.CS0_n

#######################################################
# GPIO Reads/Writes
#######################################################
signal = chip.gpio0

# Print a summary of the GPIO state
print signal

# Get the logic state of the pin
level = signal.value

# Set the logic state of the pin
signal.value = LogicLevel.LOW

#######################################################
# GPIO Configuration
#######################################################
# Set the mode of a GPIO
signal.mode = OutputMode.PUSH_PULL

#######################################################
# Clock Configuration
#######################################################
clock = chip.clock

# Print the clock state
print clock

# Set the clock frequency
# Use clock.divider to set the divider register directly
clock.frequency = 6 * 1000 * 1000 # 6 MHz

#######################################################
# Event Counter
#######################################################
counter = chip.event_counter

# Print a summary of the counter state 
print counter

# Get count
count = counter.count
(count, overflowed) = counter.count_with_overflow

# Set the count
counter.count = 10

# Configure the counter
counter.mode = EventCounterMode.NEGATIVE_PULSE

#######################################################
# OTP ROM Lock Byte
#######################################################
lock = c.lock

# Print a summary of the lock
print lock

# Lock the USB vendor ID
lock.vid = LockState.LOCKED

#######################################################
# OTP ROM USB Configuration
#######################################################
usb = c.usb

# Print a summary of the USB configuration
print usb

# Set the product string
usb.product_string = "ACME Widget"
c.usb = usb
print lock  # The product_string field is now locked

# Set the power mode
usb.power_mode = PowerMode.BUS_AND_REGULATOR_ON
c.usb = usb
print lock  # The power_mode field is now locked

#######################################################
# OTP ROM Pin Configuration
#######################################################
pins = c.pin_config

# Print a summary of the PIN configuration
print pins

# Print a summary of the config for one pin
print pins.gpio1
print pins.vpp

# Print the clock configuration
print pins.clock

# NOTE: The entire pin configuration must be set at one
# time.  The following example modifies several of the pins and
# then commit the entire config to the OTP ROM at once.

# Set a pin function
pins.gpio1.function = OutputMode.PUSH_PULL

# Set a pin suspend logic level
pins.miso.suspend_level = LogicLevel.HIGH
pins.miso.suspend_mode  = OutputMode.OPEN_DRAIN

# Set a pin wakeup config
pins.vpp.wakeup_level = LogicLevel.LOW
pins.vpp.wakeup_mask  = True

# Set the initial clock freqeuency
pins.clock.frequency = 6 * 1000 * 1000 # 6 MHz

# Write the config to the ROM
c.pin_config = pins
print lock # The pin_config field is now locked

Library Structure

This library is organized into four distinct parts, core, data, chip, and usb.

core

This component is the main high-level, Pythonic API and the one most users will use.

It exposes the various features of the CP2130 as objects. Configuration is done via mutable properties. Data is read and written via methods on the objects.

data

This component provides enums for the fields in the CP2130 configuration.

Using explicit enums, rather than the integer encodings used in the hardware, has two advantages. Most importantly, it makes the code self-documenting. Secondly, the CP2130 uses different encodings for some commands. The enums hides those differences.

chip

This component is a low-level API mirroring the native CP2130 commands.

The cp2130.chip object exposes a method for command in the CP2130 interface. These methods return or take register objects defined in the cp2130.register package, which expose the register fields as mutable properties for easy access and modification.

Most users will never need to use this component directly.

usb

This component is an abstraction over the USB interface used to access this CP2130.

Currently PyUSB and python-libusb1 backends are supplied.

Contributing

Please submit bugs, questions, suggestions, or (ideally) contributions as issues and pull requests on GitHub.

Maintainers

David R. Bild

• https://www.davidbild.org
• https://github.com/drbild

License

Copyright 2017 David R. Bild

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License from the LICENSE.txt file or at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

cp2130's Issues

OSError: [WinError 126] The specified module could not be found

The code run fail right at the 3rd line "chip = cp2130.find()"
Below is all the log. I tried to disable "libusb1" to force it use "pyusb" but also failed to detect device.

I check the connection with hardware is OK. I also could see the SPI device in the device manager. I used the verified Application for my HW to check the SPI communication with HW, and everything is OK.

BTW, I'm using Windows 8 and python 3.6.2.

Traceback (most recent call last):
  File "31-cp2130.py", line 6, in <module>
    chip = cp2130.find()
  File "C:\Users\user_name\AppData\Local\Programs\Python\Python36-32\lib\site-packa
ges\cp2130\__init__.py", line 32, in find
    from cp2130.usb import libusb1 as usb
  File "C:\Users\user_name\AppData\Local\Programs\Python\Python36-32\lib\site-packa
ges\cp2130\usb\libusb1\__init__.py", line 17, in <module>
    from cp2130.usb.libusb1.core import *
  File "C:\Users\user_name\AppData\Local\Programs\Python\Python36-32\lib\site-packa
ges\cp2130\usb\libusb1\core.py", line 18, in <module>
    from cp2130.usb.libusb1.hotplug import HotplugListener, HotpluggedDevice
  File "C:\Users\user_name\AppData\Local\Programs\Python\Python36-32\lib\site-packa
ges\cp2130\usb\libusb1\hotplug.py", line 19, in <module>
    import usb1
  File "C:\Users\user_name\AppData\Local\Programs\Python\Python36-32\lib\site-packa
ges\usb1\__init__.py", line 61, in <module>
    from . import libusb1
  File "C:\Users\user_name\AppData\Local\Programs\Python\Python36-32\lib\site-packa
ges\usb1\libusb1.py", line 199, in <module>
    libusb = _loadLibrary()
  File "C:\Users\user_name\AppData\Local\Programs\Python\Python36-32\lib\site-packa
ges\usb1\libusb1.py", line 173, in _loadLibrary
    return dll_loader('libusb-1.0' + suffix, **loader_kw)
  File "C:\Users\user_name\AppData\Local\Programs\Python\Python36-32\lib\ctypes\__i
nit__.py", line 348, in __init__
    self._handle = _dlopen(self._name, mode)
OSError: [WinError 126] The specified module could not be found

Typo / Bug in spi.py

Thanks for writing and sharing such a useful python package. I just found a bug in the spi.py file.

There is an typo in the method "write" in the SPIChannel class. Lines 92 and 93 are

    op = lambda: self.chip.write(data)
    return self._do(op, data)

And, line 93 should be

    return self._do(op, cs_hold)

Cheers,
SaeWoo

PyUSB

Great library!

For me to get it to work I had to change the order of imports in __init (https://github.com/drbild/cp2130/blob/master/cp2130/__init__.py#32) as the usb import did not raise an exception, but it then failed with LIBUSB_ERROR_NOT_SUPPORTED [-12] error. However import pyusb first worked well

I also had to remove the call to is_kernel_driver_active in https://github.com/drbild/cp2130/blob/master/cp2130/usb/pyusb.py as it was marked as NotImplemented.

I have pyusb 1.2.1 installed. (import usb, usn._version.version)

array.array.to_string is deprecated in python 3 and removed in 3.9

The straightforward fix would simply be to use to_bytes instead, although this would break backwards compatibility with python 2. However, since python 2 hasn't been supported in four years, I don't think that should be a problem.

Seems this was noticed a while back and a PR was opened here. #5.
I'm quite happy to make this change myself.

Help

Hi, I am using cp2130 now. A questions, the document say to configure the pin's mode (gpio, usb, spi) need a site-software named "XPRESS CONFIGURATOR", I did not know that means I must use "XPRESS CONFIGURATOR"? Can I configure it by codeing with the api? (with out XPRESS CONFIGURATOR)