stephendpmurphy/shost

💻 shost - GUI, CLI and static library for connecting to FTDI MPSSE capable devices

MPSSE-CLI

FTDI MPSSE CLI application for SPI, I2C and GPIO control

Getting started

To get started with the libMPSSE library you will need a couple pieces of software and a piece of hardware.

• CMake
• FTDI D2xx driver
• MPSSE capable FTDI device

Retrieving the source

To begin, you will need to clone this project to your dev machine

$ git clone https://github.com/stephendpmurphy/mpsse-cli.git
$ cd mpsse-cli
$ git submodule update --init --recursive

Building the CLI application

Once you have installed the required tools mentioned above and retrieved the source you can build the CLI application

$ cd mpsse-cli
$ mkdir -p build
# Debug build
$ cmake -DCMAKE_BUILD_TYPE=Debug ..
# OR
# Release build
$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ make -j8

Installing the CLI application

Once you have built the application, you can install to your bin folder.

$ cd build
$ sudo make install

shost's Issues

Add version file

add support for compilation and generating binaries for Windows users

Rework CMake to build lib and cli src independently

Update README with usage examples and instructions

Distribution of software

Not for right now. But in the long run it might be worthwhile to think about how to distribute the software. I favour Flatpak since it is cross-platform on most (if not all) Linux platforms. And that way we just package it once and be done with it (along with some USB access rules that should be interesting). Although distribution via dnf or apt would also be really cool. But that would require more maintenance and audits to get it into the main repo's. What do you think @stephendpmurphy?

If a full byte isn't provided with the -d option, it will improperly fill from the previous byte

Passing a buffer of:

-d 0x02,0xA

Results in a byte array of:

0x02,0xA2

Add note about udev rules not reloading on WSL2

During the udev rule install on a fresh WSL2 instance, the rules reload will fail. The service has to first be restarted using sudo service udev restart.

add release workflow for publishing artifacts on commits to main

I2c -a option does note parse correctly

Change out arg parser for more common method

I was interested in writing my own arg parser, but it got ugly pretty quickly. It would be nice to use a method described here.

Add i2c device discovery similar to i2cdetect

Move existing MPSSE functionality to the open-source lib

https://github.com/l29ah/libmpsse
https://www.intra2net.com/en/developer/libftdi/index.php
https://github.com/aruna-rov/Aruna/tree/master/cmake

add I²C support

Is it possible to add I²C support?
Should be possible using the libmpsse library. I used it before to interface with I²C devices.

Don't allow length to be overwritten when set via a -d option

Currently if you were to execute a Write transfer providing a buffer via the -d option, as well as passing a -l option. The last option to be parsed will be the one to set the length. We want to prioritize setting the length based on the buffer size. This will likely become more complex when implementing SPI Read/Writes

Build libftdi and libmpsse as part of the shost build process

Seperate documentation between Building and Installation

Right now installation is technically build instructions since it is the only way currently to retrieve a working binary.. Later there will be multiple methods of building, thus we want to separate them as such.

Rename app to "shost"

Create a lib from shost files to be linked against our CLI main

Update license to be GPLv2

Add an output option to allow writing the RX buffer to a file

It would be awesome to have a -o / --output option for specifying a filepath to output the RX buffer to

Allow building the /lib on it's own. Currently only builds as a dep of the CLI

Make the getConnectedDevices API return an object with device info

Currently the API will return a number of connected devices and then optionally print the device info. Instead we should make it return an object with all the connected device info inside AND a count. Leave it to the integrating app to handle printing data

Separate the open, close and xfer so an interface can be left open between transfers

The current shost_xfer_begin function opens, transfers and then closes an interface. We would like to leave the interface open so transactions can be sent and received at will without constantly opening and closing the interface. This would mean expanding the API to

int shost_xfer_open(shost_xfer_t *xfer) { ... }
int shost_xfer_begin(shost_xfer_t *xfer) { ... }
int shost_xfer_close(shost_xfer_t *xfer) { ... }

This would mean the shost_xfer_t object now needs to store the Protocol context so it can be shared across function calls. The shost_xfer_open and shost_xfer_close would just call a virtual _open and a public close function. The open requires context and specific modes and params based on the interface. The close just generically closes the mpsse context which the Protocol class is storing.

Add dependencies to the build process

libftdi can be built as a dependency with a static library generated. libmpsse should then just have it's source built in with our app, and then our app can link against libftdi. This should hopefully give us a single shost.a that can be referenced and linked against.

Document remaining shost lib code (SPI, I2C, Protocol)

renaming cli tool

I was thinking that this tool would be pretty handy for a lot of people. So when people use it to try out a new spi/i2c/whatever device they will use the cli frequently. So I think it is important to make it as easy as possible. I was wondering if typing mpsse-cli into the terminal is maybe a bit to long, and the cli part is redundant since its already clear it's a cli tool since your typing it in the terminal. Just like website having a www.example-site.com. The "site" part unnecessary since its already clear it's a website. I hope you get what I am saying. The current name is however very clear in its purpose and need little explaining.

I was maybe thinking something like just "ft" (because it works with FTdi chips) that would be very quick to type in the terminal

# ft spi -c 0 -x w -l 8 -d 0xDD,0xEE,0xAA,0xDD,0xBB,0xEE,0xEE,0xFF

instead of:

# mpsse-cli spi -c 0 -x w -l 8 -d 0xDD,0xEE,0xAA,0xDD,0xBB,0xEE,0xEE,0xFF

What are your thought? Are you open to the idea of changing it? The repo and application can keep the same name, only the binary needs change. We could also do something like mpsse or ftdi, but I think the shorter the command the better :).

I2c protocol class name reports SPI

add Github workflows for build validation on commits to develop

Include and build the open source MPSSE and FTDI1 libraries as part of compilation

I would like to have our app be as easy to use as possible with minimal tools installed. This would mean statically compiling both the open source MPSSE and FTDI1 libs and building them in with our final executable. Thoughts? The FTDI1 project will be easy enough since it's based on CMake but the MPSSE uses Autotools 🥴 - I think we can use something like this to build it with our CMake build.

Set the RX and TX buffers to be a pointer in the xfer object

The RX and TX buffers are currently hard coded to 256bytes. We can instead make these into pointers which will allow the end user to determine their transfer lengths and not be constricted by the lib

Utilize channel (-c) option

Currently the channel is captured but we always use channel 0

Move API to be written in C and write C++ bindings to wrap the C API

Implement the ---list option using the ftdi lib

The --list option currently does not function. Need to replace with source from libftdi1 to show available connected devices.

Implement a logging/verbosity feature

We currently have some printfs within the library. We should be able to turn off all logging or enable it as needed.

I²C: FT2232H receiving ACK while the slave did not ACKed

During testing of my branch I noticed that when there is no slave connected to the FT2232H and when checking for an ACK with (GetAck(mpsse) == ACK) returns true even when no I²C device is attached. This will require some further investigation. It did work before though (before the C++ part, and I did not alter the write/read code). So not sure why it suddenly stopped working.

I2c -r option does not parse correctly

I2C seg faults when no devices are connected to the PC.

SPI Transfers can't exceed 6Mhz

A bug has been created in the libmpsse repository. SPI Transfers can't exceed 6Mhz. Once you do, the lines become erratic.

rename the src folder to cli

We intend to have a lib, CLI and GUI for the shost application. So rename src to cli since it's the CLI source code which interfaces with the lib. The same will be done for the GUI.