USB ISS Python Module¶
Contents¶
USB-ISS Python Library¶
Python library for the USB-ISS module.
- USB ISS module documentation:
- https://www.robot-electronics.co.uk/htm/usb_iss_tech.htm
- Python API documentation:
- https://usb-iss.readthedocs.io
Features¶
- I2C Mode
- IO Mode
- SPI Mode
- Serial Mode
Usage Example¶
from usb_iss import UsbIss, defs
# Configure I2C mode
iss = UsbIss()
iss.open("COM3")
iss.setup_i2c()
# Write and read back some data
iss.i2c.write(0xC4, 0, [0, 1, 2]);
data = iss.i2c.read(0xC4, 0, 3)
print(data)
# [0, 1, 2]
Installing¶
pip install usb-iss
Supports Python 2.7 & 3.5+.
This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.
usb_iss package¶
-
class
usb_iss.
UsbIss
(dummy=False, verbose=False)[source]¶ Bases:
object
Main object used to interact with the USB_ISS device.
Example
from usb_iss import UsbIss, defs # Configure I2C mode iss = UsbIss() iss.open("COM3") iss.setup_i2c() # Write and read back some data iss.i2c.write(0xC4, 0, [0, 1, 2]); data = iss.i2c.read(0xC4, 0, 3) print(data) # [0, 1, 2]
Parameters: - dummy (bool) – Use a dummy driver stub, for testing.
- verbose (bool) – Print debug output to the console.
-
serial
¶ Attribute to use for Serial UART access. See
serial_.Serial
for the full set of Serial methods.Type: serial_.Serial
-
open
(port)[source]¶ Open the specified serial port for communication with the USB_ISS module.
Parameters: port (str) – Serial port to use for usb_iss communication.
-
setup_i2c
(clock_khz=400, use_i2c_hardware=True, io1_type=None, io2_type=None)[source]¶ Issue an ISS_MODE command to set the operating mode to I2C + IO.
Parameters: - clock_khz (int) – I2C clock rate in kHz. See https://www.robot-electronics.co.uk/htm/usb_iss_tech.htm for a list of valid values.
- use_i2c_hardware (bool) – Use the USB_ISS module’s hardware I2C controller.
- io1_type (defs.IOType) – IO1 mode (or None for no change)
- io2_type (defs.IOType) – IO2 mode (or None for no change)
-
setup_i2c_serial
(clock_khz=400, use_i2c_hardware=True, baud_rate=9600)[source]¶ Issue an ISS_MODE command to set the operating mode to I2C + Serial.
Parameters: - clock_khz (int) – I2C clock rate in kHz. See https://www.robot-electronics.co.uk/htm/usb_iss_tech.htm for a list of valid values.
- use_i2c_hardware (bool) – Use the USB_ISS module’s hardware I2C controller.
- baud_rate (int) – Baud rate for the serial interface.
-
setup_spi
(spi_mode=<SPIMode.TX_ACTIVE_TO_IDLE_IDLE_LOW: 144>, clock_khz=500)[source]¶ Issue an ISS_MODE command to set the operating mode to SPI.
Parameters: - spi_mode (defs.SPIMode) – SPI mode option to use.
- clock_khz (int) – SPI clock rate in kHz.
-
setup_io
(io1_type=None, io2_type=None, io3_type=None, io4_type=None)[source]¶ Issue an ISS_MODE command to set the operating mode to IO.
Parameters: - io1_type (defs.IOType) – IO1 mode (or None for no change)
- io2_type (defs.IOType) – IO2 mode (or None for no change)
- io3_type (defs.IOType) – IO3 mode (or None for no change)
- io4_type (defs.IOType) – IO4 mode (or None for no change)
-
change_io
(io1_type=None, io2_type=None, io3_type=None, io4_type=None)[source]¶ Issue an ISS_MODE command to change the current IO mode without affecting serial or I2C settings.
Parameters: - io1_type (defs.IOType) – IO1 mode (or None for no change)
- io2_type (defs.IOType) – IO2 mode (or None for no change)
- io3_type (defs.IOType) – IO3 mode (or None for no change)
- io4_type (defs.IOType) – IO4 mode (or None for no change)
-
setup_serial
(baud_rate=9600, io3_type=None, io4_type=None)[source]¶ Issue an ISS_MODE command to set the operating mode to Serial + IO.
Parameters: - baud_rate (int) – Baud rate for the serial interface.
- io3_type (defs.IOType) – IO3 mode (or None for no change)
- io4_type (defs.IOType) – IO4 mode (or None for no change)
Submodules¶
usb_iss.defs module¶
Definitions from http://www.robot-electronics.co.uk/htm/usb_iss_tech.htm.
-
class
usb_iss.defs.
ResponseCode
[source]¶ Bases:
enum.Enum
Note: For I2C: NACK = 0x00, ACK = Non-zero.
-
NACK
= 0¶
-
ACK
= 255¶
-
-
class
usb_iss.defs.
SubCommand
[source]¶ Bases:
enum.Enum
An enumeration.
-
ISS_VERSION
= 1¶
-
ISS_MODE
= 2¶
-
GET_SER_NUM
= 3¶
-
-
class
usb_iss.defs.
Mode
[source]¶ Bases:
enum.Enum
An enumeration.
-
IO_MODE
= 0¶
-
IO_CHANGE
= 16¶
-
I2C_S_20KHZ
= 32¶
-
I2C_S_50KHZ
= 48¶
-
I2C_S_100KHZ
= 64¶
-
I2C_S_400KHZ
= 80¶
-
I2C_H_100KHZ
= 96¶
-
I2C_H_400KHZ
= 112¶
-
I2C_H_1000KHZ
= 128¶
-
SPI_MODE
= 144¶
-
SERIAL
= 1¶
-
-
class
usb_iss.defs.
ModeError
[source]¶ Bases:
enum.Enum
An enumeration.
-
UNKNOWN_COMMAND
= 5¶
-
INTERNAL_ERROR_1
= 6¶
-
INTERNAL_ERROR_2
= 7¶
-
-
class
usb_iss.defs.
IOType
[source]¶ Bases:
enum.Enum
An enumeration.
-
OUTPUT_LOW
= 0¶
-
OUTPUT_HIGH
= 1¶
-
DIGITAL_INPUT
= 2¶
-
ANALOGUE_INPUT
= 3¶
-
-
class
usb_iss.defs.
SPIMode
[source]¶ Bases:
enum.Enum
An enumeration.
-
TX_ACTIVE_TO_IDLE_IDLE_LOW
= 144¶
-
TX_ACTIVE_TO_IDLE_IDLE_HIGH
= 145¶
-
TX_IDLE_TO_ACTIVE_IDLE_LOW
= 146¶
-
TX_IDLE_TO_ACTIVE_IDLE_HIGH
= 147¶
-
-
class
usb_iss.defs.
Command
[source]¶ Bases:
enum.Enum
An enumeration.
-
I2C_SGL
= 83¶
-
I2C_AD0
= 84¶
-
I2C_AD1
= 85¶
-
I2C_AD2
= 86¶
-
I2C_DIRECT
= 87¶
-
I2C_TEST
= 88¶
-
SPI
= 97¶
-
SERIAL
= 98¶
-
SET_PINS
= 99¶
-
GET_PINS
= 100¶
-
GET_AD
= 101¶
-
-
class
usb_iss.defs.
I2CDirect
[source]¶ Bases:
enum.Enum
An enumeration.
-
START
= 1¶
-
RESTART
= 2¶
-
STOP
= 3¶
-
NACK
= 4¶
-
READ1
= 32¶
-
READ2
= 33¶
-
READ3
= 34¶
-
READ4
= 35¶
-
READ5
= 36¶
-
READ6
= 37¶
-
READ7
= 38¶
-
READ8
= 39¶
-
READ9
= 40¶
-
READ10
= 41¶
-
READ11
= 42¶
-
READ12
= 43¶
-
READ13
= 44¶
-
READ14
= 45¶
-
READ15
= 46¶
-
READ16
= 47¶
-
WRITE1
= 48¶
-
WRITE2
= 49¶
-
WRITE3
= 50¶
-
WRITE4
= 51¶
-
WRITE5
= 52¶
-
WRITE6
= 53¶
-
WRITE7
= 54¶
-
WRITE8
= 55¶
-
WRITE9
= 56¶
-
WRITE10
= 57¶
-
WRITE11
= 58¶
-
WRITE12
= 59¶
-
WRITE13
= 60¶
-
WRITE14
= 61¶
-
WRITE15
= 62¶
-
WRITE16
= 63¶
-
usb_iss.i2c module¶
-
class
usb_iss.i2c.
I2C
(drv)[source]¶ Bases:
object
Use the USB_ISS device to perform I2C accesses.
Example
from usb_iss import UsbIss, defs # Configure I2C mode iss = UsbIss() iss.open("COM3") iss.setup_i2c() # Write and read back some data iss.i2c.write(0xC4, 0, [0, 1, 2]); data = iss.i2c.read(0xC4, 0, 3) print(data) # [0, 1, 2]
-
write
(address, register, data)[source]¶ Write multiple bytes to a device with a one-byte internal register address. This is an alias for the write_ad1 method, used by the majority of devices.
Parameters: - address (int) – I2C address of the device.
- register (int) – Internal register address to write (0x00 - 0xFF).
- data (list of int) – List of bytes to write to the device.
-
read
(address, register, byte_count)[source]¶ Read multiple bytes from a device with a one-byte internal register address. This is an alias for the read_ad1 method, used by the majority of devices.
Parameters: - address (int) – I2C address of the device.
- register (int) – Internal register address to read (0x00 - 0xFF).
- byte_count (int) – Number of bytes to read.
Returns: List of bytes read from the device.
Return type: list of int
-
write_single
(address, data_byte)[source]¶ Write a single byte to an I2C device.
Parameters: - address (int) – I2C address of the device.
- data_byte (int) – Data byte to write to the device.
-
read_single
(address)[source]¶ Read a single byte from an I2C device.
Parameters: address (int) – I2C address of the device. Returns: Data byte read from the device. Return type: int
-
write_ad0
(address, data)[source]¶ Write multiple bytes to a device without internal register addressing, or where the internal register address does not require resetting.
Parameters: - address (int) – I2C address of the device.
- data (list of int) – List of bytes to write to the device.
-
read_ad0
(address, byte_count)[source]¶ Read multiple bytes from a device without internal register addressing, or where the internal register address does not require resetting.
Parameters: - address (int) – I2C address of the devie.
- byte_count (int) – Number of bytes to read.
Returns: List of bytes read from the device.
Return type: list of int
-
write_ad1
(address, register, data)[source]¶ Write multiple bytes to a device with a one-byte internal register address.
Parameters: - address (int) – I2C address of the device.
- register (int) – Internal register address to write (0x00 - 0xFF).
- data (list of int) – List of bytes to write to the device.
-
read_ad1
(address, register, byte_count)[source]¶ Read multiple bytes from a device with a one-byte internal register address.
Parameters: - address (int) – I2C address of the device.
- register (int) – Internal register address to read (0x00 - 0xFF).
- byte_count (int) – Number of bytes to read.
Returns: List of bytes read from the device.
Return type: list of int
-
write_ad2
(address, register, data)[source]¶ Write multiple bytes to a device with a two-byte internal register address.
Parameters: - address (int) – I2C address of the device.
- register (int) – Internal register address to write (0x0000 - 0xFFFF).
- data (list of int) – List of bytes to write to the device.
-
read_ad2
(address, register, byte_count)[source]¶ Read multiple bytes from a device with a two-byte internal register address.
Parameters: - address (int) – I2C address of the device.
- register (int) – Internal register address to read (0x0000 - 0xFFFF).
- byte_count (int) – Number of bytes to read.
Returns: List of bytes read from the device.
Return type: list of int
-
direct
(data)[source]¶ Send a custom I2C sequence to the device. See https://www.robot-electronics.co.uk/htm/usb_iss_i2c_tech.htm for a full set of examples.
Parameters: data (list of defs.I2CDirect) – List of I2CDirect
commands and data.Returns: List of bytes read from the device. Return type: list of int Example
# Equivalent to iss.i2c.write_single(0x40, 0x55) iss.i2c.direct([ defs.I2CDirect.START, defs.I2CDirect.WRITE2, 0x40, 0x55, defs.I2CDirect.STOP, ]);
-
usb_iss.io module¶
-
class
usb_iss.io.
IO
(drv)[source]¶ Bases:
object
Use the USB_ISS device to perform IO accesses.
Example
from usb_iss import UsbIss # Configure IO mode with all outputs low iss = UsbIss() iss.open("COM3") iss.setup_io(io1_type=defs.IOType.OUTPUT_LOW, io2_type=defs.IOType.OUTPUT_LOW, io3_type=defs.IOType.OUTPUT_LOW, io4_type=defs.IOType.OUTPUT_LOW) # Drive IO1 & IO3 high iss.io.set_pins(1, 0, 1, 0);
-
set_pins
(io0, io1, io2, io3)[source]¶ Set the digital output pins high or low. This command only operates on pins that have been configured as digital outputs. Digital or analogue inputs or pins that are used for I2C or serial are not affected.
For each argument, set to 0 to drive low and 1 to drive high.
Parameters: - io0 (int) – IO0 output value.
- io1 (int) – IO1 output value.
- io2 (int) – IO2 output value.
- io3 (int) – IO3 output value.
-
usb_iss.serial_ module¶
-
class
usb_iss.serial_.
Serial
(drv)[source]¶ Bases:
object
Use the USB_ISS device to perform Serial UART accesses.
Example
from usb_iss import UsbIss # Configure Serial mode iss = UsbIss() iss.open("COM3") iss.setup_serial() # Write and read some data iss.serial.transmit([0x48, 0x65, 0x6c, 0x6c, 0x6f]); iss.serial.transmit_string("Hello!") data = iss.serial.receive() print(data) # [72, 105]
-
transmit
(data)[source]¶ Transmit data over the Serial UART interface.
Parameters: data (list of int) – List of bytes to transmit.
-
transmit_string
(string, encoding='utf-8')[source]¶ Transmit a string over the Serial UART interface.
Parameters: - string (str) – String to transmit.
- encoding (str) – Encoding of the string.
-
receive
(timeout_ms=100)[source]¶ Receive data over the Serial UART interface. Returns once no data is received for timeout_ms.
Parameters: timeout_ms (int) – Returns once no data is received for this period. Returns: List of bytes received. Return type: list of int
-
receive_string
(timeout_ms=100, encoding='utf-8')[source]¶ Receive a string over the Serial UART interface. Returns once no data is received for timeout_ms.
Parameters: - timeout_ms (int) – Returns once no data is received for this period.
- encoding (str) – Encoding of the string.
Returns: String received.
Return type: string
-
usb_iss.spi module¶
-
class
usb_iss.spi.
SPI
(drv)[source]¶ Bases:
object
Use the USB_ISS device to perform SPI accesses.
Example
from usb_iss import UsbIss # Configure SPI mode iss = UsbIss() iss.open("COM3") iss.setup_spi() # Write and read some data in a single transfer data = iss.spi.transfer([0, 1, 2]); print(data) # [4, 5, 6]
Contributing¶
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions¶
Report Bugs¶
Report bugs at https://github.com/sneakypete81/usb_iss/issues.
If you are reporting a bug, please include:
- Your operating system name and version.
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
Fix Bugs¶
Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.
Implement Features¶
Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.
Write Documentation¶
The USB-ISS Python Library could always use more documentation, whether as part of the official USB-ISS Python Library docs, in docstrings, or even on the web in blog posts, articles, and such.
Submit Feedback¶
The best way to send feedback is to file an issue at https://github.com/sneakypete81/usb_iss/issues.
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!¶
Ready to contribute? Here’s how to set up usb_iss for local development.
Fork the usb_iss repo on GitHub.
Clone your fork locally:
$ git clone git@github.com:your_name_here/usb_iss.git $ cd usb_iss
Install your local clone (plus developer dependencies) into a virtualenv and activate it:
$ pip install virtualenv $ make develop $ . .venv/bin/activate
Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
$ make test-all
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature
Submit a pull request through the GitHub website.
Pull Request Guidelines¶
Before you submit a pull request, check that it meets these guidelines:
- The pull request should include tests.
- If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring.
- The pull request should work for Python 2.7, 3.5, 3.6 and 3.7. Check https://travis-ci.org/sneakypete81/usb_iss/pull_requests and make sure that the tests pass for all supported Python versions.
Deploying¶
A reminder for the maintainers on how to deploy:
$ # Update CHANGELOG.rst
$ bumpversion [major|minor|patch]
$ git push
$ git push --tags
Travis will then deploy to PyPI if tests pass.
Changelog¶
1.0.0 (2019-10-16)¶
- BREAKING CHANGE: Remember the previous IO state in the setup_* methods
- BREAKING CHANGE: Improve the serial mode API
- Add verbose logging option
0.3.1 (2018-07-02)¶
- Fix Python2 serial interface
0.3.0 (2018-05-28)¶
- Add SPI support
- Add Serial UART support
- Improve test coverage
0.2.4 (2018-05-23)¶
- Add SPI, Serial and IO setup methods
0.2.3 (2018-05-22)¶
- Fix and test Travis PyPI auto-deploy
0.2.0 (2018-05-21)¶
- Generate documentation
- Add dummy driver option for test purposes
- Configure I/O as input by default
- Add i2c.read/write aliases for read_ad1/write_ad1
- Update setup_i2c to split out clk_khz and use_i2c_hardware parameters
0.1.0 (2018-04-19)¶
- Initial release
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line