# Welcome to the TinI/O Manual! Welcome to the TinI/O manual. In this document you can find information about installing, configuring and using TinI/O, the simple interface to I/O. ----- # What is TinI/O? Simply put, TinI/O is a Linux CLI program that, when combined with a certain chip, adds more general purpose input/output (GPIO) pins to your computer. They can then be used to control custom electronics outside the computer, for example a MOSFET driving a fan, a LED, a sensor or anything that can be controlled or read from with logic ones and zeros. That certain chip is in this case, the [Cypress CY7C65211 USB-Serial Bridge Controller](http://www.cypress.com/products/usb-uart-controller-gen-2). TinI/O sends commands to it over USB using [the libcyusbserial library](https://github.com/cyrozap/libcyusbserial) made by cyrozap and [the libusb library](http://libusb.info/). When the chip recieves the command, it changes or reads the state of the requested GPIO pin. Using TinI/O is free (as beer _and_ speech), because it's licensed under GNU General Public License. You can use it free of any charges, but you need a TinI/O compatible board ([like this one](http://www.cypress.com/documentation/development-kitsboards/psoc-4-cy8ckit-049-4xxx-prototyping-kits)), that (at the time of writing) costs $4 at Cypress.com. # Where to start? To start using TinI/O, make sure you have: - A computer running some sort of Linux that has: + A free USB port to use the board with + libusb 1.0 and its headers installed + 16 MB of free space (or 8 for the bare minimum) + A C and C++ compiler (preferably gcc and g++) - A TinI/O compatible board They can be obtained from Cypress, the manufacturer of the chip. The board I personally use and recommend is the [CY8CKIT-049-4xxx PSoC4 prototyping kit](http://www.cypress.com/documentation/development-kitsboards/psoc-4-cy8ckit-049-4xxx-prototyping-kits), but there are more of them out there, for example, the [CYUSBS234 USB-Serial (Single Channel) Development Kit](http://www.cypress.com/documentation/development-kitsboards/cyusbs234-usb-serial-single-channel-development-kit). # Building and installing TinI/O Installing TinI/O is very easy - just `cd` inside the `tinio` directory and run `make`. When the installation completes, run `make install`. With everything installed, proceed to the next chapter. # Flashing the board Before you use your board with TinI/O, you must program its chip with a custom flash file that will make the board compatible with TinI/O. The flash files are located in the `/usr/share/tinio/flash` directory and can be flashed to the board with the installed `cy-config` utility. There are 2 flash files with slightly different pin configurations: `5-5.cyusbd` and `3-3cs.cyusbd`. The 5-5 file sets half (5) of the GPIO pins as outputs and the other half as inputs. The 3-3cs sets 3 of the pins as outputs and 4 as inputs and 1 pin as a CapSense capacitive touch button and 1 as its output. See the table for the exact pin configuration: | GPIO Pin | 5-5 config | 3-3cs config | | --- | --- | --- | | 0 | Input | RESERVED - decouple to ground with a 2n2 capacitor | | 1 | Input | Input | | 2 | Input | Capsense button - connect to a metal button surface | | 3 | Input | Capsense out - connect to an input to read | | 4 | Input | Input| | 5 | UART Tx - Don't connect | UART Tx - Don't connect | | 6 | UART Rx - Don't connect | UART Rx - Don't connect | | 7 | Output | Input | | 8 | Output | Output | | 9 | Output | Output | | 10 | Output | Output | | 11 | Output | Input | After you've decided which configuration you'll use, run the configuration utility with the path of the flash file as an argument , e.g.:`cy-config /usr/share/tinio/flash/5-5.cyusbd`. A menu will appear: ``` --------------------------------------------------------------------------------- Device Number | VID | PID | INTERFACE NUMBER | FUNCTIONALITY --------------------------------------------------------------------------------- 0 |1d6b |2 | 0 | NA 1 |413c |3016 | 0 | NA 2 |461 |10 | 0 | NA 2 |461 |10 | 1 | NA 3 |1d6b |1 | 0 | NA 4 |8bb |2902 | 0 | NA 4 |8bb |2902 | 1 | NA 4 |8bb |2902 | 2 | NA 4 |8bb |2902 | 3 | NA 5 |4b4 |4 | 0 | NA 5 |4b4 |4 | 1 | NA 6 |1d6b |1 | 0 | NA 7 |1d6b |1 | 0 | NA 8 |1d6b |2 | 0 | NA 9 |1d6b |1 | 0 | NA 10 |1d6b |1 | 0 | NA --------------------------------------------------------------------------------- Cydevices 11------------------------------------------------------------------- 1: Print list of devices 2: Select device...No device selected !! ``` At this point, you want to look for the device `4b4` in the VID column. Find its device number. In the example above, the device we're looking for has the device number 5. Select the `Select Device` option in the menu by entering `2`. ``` 2 Enter Device number to be selected.. ``` Enter the device number you remembered in the previous step. ``` 5 Enter interface number.. ``` Enter __the device's highest interface number in the table__. In the example it's 1, but it can also be 2. ``` 1 File opened successfully Bytes successfully read Programming Flash is done File stream closed ------------------------------------------------------------------- 1: Print list of devices 2: Change device selection--selected device: [Device number 5] : [Interface No 1] : NA ^C ``` This is how a successful flashing output should look like. If it doesn't: + If it gives you a fopen() error, the file you tried to flash doesn't exist or (rarely happens, but still) has a too long path. Find the file or move it to a less obscure folder. + Make sure you used a right device and file + Try running the utility as root ## Creating your own configs If you want to program your device your own way, you can do it with Cypress' [USB-Serial Configuration Utility](http://www.cypress.com/documentation/software-and-drivers/usb-serial-software-development-kit). However, you must follow some guidelines to make your configuration TinI/O compatible. The device must be configured to: + PHDC Interface + UID and VID left default + SCB: UART 2-pin # Using TinI/O TinI/O is pretty simple to use. To see a quick usage reminder, run `tinio` in the terminal, but here's a more extensive ## Usage | __Option__ | __Action__ | |------------|------------| | -d | Sets the device number. 0 if left out. Up to 15 devices. | | -i | Sets the interface number. 0 if left out. 0-255. | | -s | Sets the specified pin's value to the value specified with the -v option. 0-11. | | -r | Reads the pin's value and outputs it to the stdout. 0-11. | | -v | Specifies the output value. Either 0 or 1, other numbers default to 1. | | -e | Enables expert mode. The expert mode enables you to write to reserved pins (5&6) and shouldn't be enabled unless you know what you're doing. | ## Practical examples The two basic functions of TinI/O are reading and writing to I/O on a single device: - To read, run `tinio -r` with replaced with the desired pin. The result will be printed to the stdout, followed by a newline. - To set, run `tinio -s -v` with replaced with the desired pin and replaced with the value you want to write. TinI/O is capable of handling up to 16 devices at once with the `-d` option, but there isn't a reliable way of identifying them. The best way to ensure the correct device order is to look at the device tree with `lsusb` and check which device comes first - it will have the first device number (0). - To read from a specific device number, run `tinio -r -d` and replace with the pin number and with the device number. - To write to a specific device run `tinio -s -v -d` and replace with the pin number, with the value and with the device number. ## Using TinI/O in your projects + As the TinI/O target chip (CY7C65211) isn't a microcontroller, it can't operate without a computer connected to it. + It can't do PWM. + Its I/O has 3.3V LVTTL logic level, and it's __not__ 5V compatible. + Its maximum output current is comparable to Arduino's at 25 mA. + When using CapSense, decouple the reserved 0 pin to the ground with a 2.2 nF capacitor and don't use it. # Copyright, Links, ... [Cypress' website](http://cypress.com) [CY7C65211 Datasheet](http://http://www.cypress.com/file/139886/download) [TinI/O Github](http://github.com/kristjan-komlosi/tinio) [My Youtube channel - You may expect some videos of TinI/O there](https://www.youtube.com/channel/UCmcIwYA2I2YkmQs7xgMU-DA) ## __Copyright disclaimer__ No copyright infringement was intended to be made with this document or the TinI/O project. All of trademarks stated in this document are property of their owners. TinI/O is licensed under GNU GPL License. This document is licensed under the GNU FDL License.