Smart Tactor Development Kit User Guide
Smart Tactor Development Kit User Guide
This document will guide you through the setup and usage of your Smart Tactor Development Kit.
In this Article
Here is an abbreviated version to get you going right away:
- Plug tactors into USB interface dongle
- Plug USB interface dongle into Windows PC, and wait for driver to finish installing
- Download and run the Display Editor program
- Set the waveform parameters and hit Buzz
The core of the Smart Tactor Development Kit is the tactor, a piezoelectric actuator with integrated driving electronics designed for mounting in garments to create wearable haptic feedback anywhere on your body. Tactors are controlled through software running on a host computer that can address them directly with their unique ID, or by assigning them spatial coordinates that correspond to their location relative to the body. Tactors are electrically connected to the USB interface dongle through a standard 4-wire cable, and daisy-chained together to create arrays that allow for complex multi-node haptic patterns. The cable operates on a proprietary serial protocol called CorBus that handles communication between the tactors and the host computer.
- 2 x Smart Tactor – piezo actuator with integrated driving electronics
- 2 x Tactor connector cables – plugs tactors into each other and USB interface dongle
- 1 x USB Interface Dongle – link between host computer and tactors
- 1 x USB cable – standard cable, plugs USB interface dongle into to host computer
- Fabric Snap set – method for attaching tactors to a garment
- Adhesive Velcro Patch set – secondary method for attaching tactors to garment
Connecting to Computer & Software Operation
Actuation of tactors can be controlled by two pieces of software: the Display Editor and the CorBus API.
- Display Editor download link: https://info.piezo.com/hubfs/Display%20Editor%201.0.13%20(32b).zip
- CorBus Python API package download link: https://info.piezo.com/hubfs/corbus-python.zip
The Display Editor tool is a standalone program with a GUI, designed for configuring tactors and testing them with simple manual commands. It is packaged as an executable program, so installation is as simple as copying the file to your computers Desktop, or wherever you install programs.
The CorBus API is a code library for Python that contains all the functions necessary to detect and control tactors, allowing you to create custom scripts and programs. It requires an installation of Python 2.7. The source code for the API is not yet supported by automatic install tools such as PIP, so it should be manually copied into the Python install path. The CorBus download package contains a startup guide, example scripts, and documentation for using the API. Look for the quickstart.html file in the download package to begin.
Both the API and the Display Editor are currently only supported on Windows operating systems.
Tactor Configuration and Testing with Display Editor
Once the Display Editor program is installed, plug in the USB interface dongle to your host PC with the provided cable (or any standard micro USB cable), and Windows will automatically detect and install the driver. Wait for this process to finish, which Windows will acknowledge with a notification in the task tray.
Use the provided CorBus cable to connect the dongle to the tactor. Subsequent tactors can be connected from the OUT side of the previous tactor. If a tactor is connected properly, a yellow light will indicate that it is powered – note that this light will turn off when the tactor is detected by the computer, to save power. A red light on the tactor indicates that it has been connected to the wrong side; simply swap the cable to the other side of the tactor to correct this.
With the dongle and tactors connected, run the Display Editor. It will automatically detect tactors on the bus, which may take a few moments, and then open the main “Configure Display” window. See the screenshots of these windows below for reference:
In the main window, details for each connected tactor are listed line by line. To buzz a tactor, set the desired parameters (detailed below) and click the Buzz button on the line corresponding to that tactor.
- Duration (time): duration of buzz in seconds, between 0 and 2
- The 2 second limit is to prevent accidentally running a tactor for too long. There is no inherent limit to how long the tactor can run for
- Frequency, in increments of 1 Hz between 1 Hz and 1000 Hz
- Amplitude, in increments of 0.125, between 0 (minimum) and 1 (full)
- Note: amplitude is frequency dependent; peak amplitude corresponds with the piezo resonance frequency, typically between 250 Hz and 300 Hz.
- Waveform: sine, square, triangle
- At full amplitude near resonance, Square wave commands may temporarily overload the driver. If this occurs, power cycle the tactor by unplugging and re-plugging it, and then restart the display editor.
Configuring a tactor consists of assigning it to a Site, and defining its spatial coordinates. Sites are groups meant to represent regions of the body intended to help organize tactor commands when writing programs. Create a site either from the “Site” menu, or by clicking field under the Site column for desired tactor and select “New Site”, and type in whatever name you choose. Once a site is created, add tactors to it by clicking on the field and selecting that site.
A new tab will appear with the chosen site name. Open this tab and select the tactor, then enter the desired coordinates. The units are arbitrary, intended to refer to the distance between tactors along the body, relative to an origin. For example, in the screenshot below, the tactor is assigned to the site “torso” and given the cylindrical coordinates of (0,4,0) in inches. Considering the center of the body as the origin, i.e. between the navel and spine, these coordinates would refer to the navel.
By assigning sites and spatial coordinates, you can define a mapping scheme that can be used to address tactors by their location. Using the CorBus library, these spatial coordinates can be mathematically selected, either individually or across regions. For example, with an array of tactors mounted on a belt, a program can indicate directions to the wearer for navigation, or produce a pattern to mimic the feeling of a wave passing by.
Each tactor comes preloaded with firmware that interprets signals from the CorBus and drives the piezo actuator accordingly, so hardware setup and configuration is minimal. Each tactor consists of a plastic cover, a piezo element, and a printed circuit board (PCB), and which are held together with four screws and nuts.
The plastic cover is the top side of the tactor, the side meant to contact the skin, with a window where the tip of the piezo actuator swings through the window in the cover. A rubber bumper glued to the tip of the actuator concentrates the displacement, creating a more localized sensation on the skin. The PCB forms the back side of the tactor and the mounting surface meant to contact the garment fabric. It is conformal coated to insulate the electronics and protect them from dirt buildup.
Two connectors on either side of the tactor accept a standard 4-pin PicoLock connector from Molex, part number 0151310401. They are keyed (non-reversible) to plug in one way, however, it is possible to plug them in upside down. When plugged in the correct direction, the connector should slip in easily and click into place with minimal pressure applied. These cables are readily available through distributors like Digikey, in various lengths. The cable passes four signals: +5V, Ground, and two differential data lines. The USB interface dongle has the same 4-pin connectors as the tactors, and a micro USB receptacle to plug into a computer.
Hardware Mounting Methods
For basic use, tactors can be held in hand or taped down to a surface. For their intended use in garments, the kit provides two methods for mounting tactors to a garment: fabric snaps and adhesive Velcro patches.
Snaps are recommended for more permanent garment construction, while Velcro are recommended for more flexible placement. Snaps are included loose in the kit, and can be glued to the PCB with standard superglue or epoxy. The drawing on the right shows the suggested arrangement for snap placement. The mating snaps, also included in the kit, can be punched into fabric by hand using a hammer and dowel, or with a tool. More details on these snaps and the tool can be found here:
The adhesive Velcro patches (also included in the kit) can be stuck onto the back of the tactor near the center for best results. The mating patch can be stuck to the intended mounting surface, e.g. fabric. More details on the patches can be found here: https://www.uline.com/Product/Detail/S-17170/Velcro-Brand-Tape/Velcro-Brand-Combo-Dots-Pack-3-4-Black
Display Editor can’t find the USB Interface Dongle
If Display Editor starts up but fails to detect the interface dongle, this window will appear:
This will happen in two cases: either the USB cable is not properly plugged into the USB dongle, or the driver didn’t finish installing properly. To fix the driver on Windows 10, simply plug cycle the USB cable and wait for Windows to finish driving installation (if necessary). On older versions of Windows, you may need to manually install the driver, which can be downloaded from this website: https://www.ftdichip.com/Drivers/VCP.htm
Once the driver is installed and the USB dongle is properly plugged in, Windows should recognize the device and acknowledge it with a short sound effect. Alternatively, to check that the USB dongle has been recognized, open the Window’s Device Manager and check under Ports (COM & LPT) for “USB Serial Port (COMx)”.
Case Labelling Error: On the cover of the USB interface dongle, the connectors are labeled IN and OUT, in reference to the direction that it connects to on the tactor side. However, both connectors are actually oriented as an IN, meaning they plug into the OUT side of a tactor.