# CLUE Text Telephone Transmitter ## Overview https://youtu.be/z2ht4x-8qz4 The TTY machine (a.k.a., Teletype/textphone/Minicom) is a communications device similar to a teleprinter that is used to send text messages over the public switched telephone network. The TTY was developed in the 1960s to assist deaf and hard-of-hearing users in communicating over the telephone system. It consists of a keyboard, display, and acoustic coupler for a phone handset (some also included a small continuous roll printer or interface for external printers). The TTY converts typed characters to audio signals which can be sent over the phone system to TTY machine on the receiving end, where those audio signals would be converted back to text for display. The TTY was supplanted in the 1990s by modern services such as instant messaging on computers and texting on phones (as well as video calls and video relay services for sign language use) but the technology is interesting to study, and in fact still works on some phone exchanges. In this guide we'll take a look at how the TTY uses audio tones to communicate and build our own transmitter with a CLUE capable of sending messages to a TTY machine, both in standalone mode and in Bluetooth LE mode with messages being sent from iOS or Android. https://youtu.be/vsi7gwKwP-U ## Parts ### Adafruit CLUE - nRF52840 Express with Bluetooth® LE [Adafruit CLUE - nRF52840 Express with Bluetooth® LE](https://www.adafruit.com/product/4500) Do you feel like you just don't have a CLUE? Well, we can help with that - get a CLUE here at Adafruit by picking up this sensor-packed development board. We wanted to build some projects that have a small screen and a lot of sensors. To make it compatible with existing projects, we made... In Stock [Buy Now](https://www.adafruit.com/product/4500) [Related Guides to the Product](https://learn.adafruit.com/products/4500/guides) ![Animated GIF showing CLUE board displaying data from the many on-board sensors.](https://cdn-shop.adafruit.com/product-videos/640x480/4500-04.jpg) ### Adafruit STEMMA Speaker - Plug and Play Audio Amplifier [Adafruit STEMMA Speaker - Plug and Play Audio Amplifier](https://www.adafruit.com/product/3885) Hey, have you heard the good news? With Adafruit STEMMA boards you can easily and safely plug sensors and devices together, like this **Adafruit STEMMA Speaker - Plug and Play Audio Amplifier**. Like the name implies, it's got a class D audio amplifier on board, and our... In Stock [Buy Now](https://www.adafruit.com/product/3885) [Related Guides to the Product](https://learn.adafruit.com/products/3885/guides) ![Top view of a black speaker breakout board connected to a round microcontroller via alligator clips. A music note animation emits from the speaker.](https://cdn-shop.adafruit.com/product-videos/640x480/3885-05.jpg) ### USB cable - USB A to Micro-B [USB cable - USB A to Micro-B](https://www.adafruit.com/product/592) This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller Approximately 3 feet / 1 meter long In Stock [Buy Now](https://www.adafruit.com/product/592) [Related Guides to the Product](https://learn.adafruit.com/products/592/guides) ![USB cable - USB A to Micro-B - 3 foot long](https://cdn-shop.adafruit.com/640x480/592-01.jpg) Info: # CLUE Text Telephone Transmitter ## TTY Fundamentals ## 5-Bit Encoding TTY machines send and receive audio signals (usually over the phone line) which are encoded and decoded as text. They feature a small typing keyboard, display, phone handset acoustic coupling modem, and often a small printer or printer port. TTY machines typically use a 5-bit character encoding protocol based on [Baudot code](https://en.wikipedia.org/wiki/Baudot_code) that was developed in 1870 for telegraph transmission of the Roman alphabet, numbers, and symbols. The chirping you'll hear when typing a letter on a TTY machine are 1400Hz and 1800Hz tones being shifted in 5-bit sets to represent the full character, number and symbol set. You can see the frequencies of the letter `A` visualized here -- we'll take a closer look at the specific meaning below. ![hacks_615px-Clavier_Baudot.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/762/medium640/hacks_615px-Clavier_Baudot.jpg?1588182711) ![hacks_a.png](https://cdn-learn.adafruit.com/assets/assets/000/090/763/medium640/hacks_a.png?1588183343) The protocol is defined in [this specification document](https://www.itu.int/rec/T-REC-V.18-200011-I/en). Here are some relevant selections: > A.1 Mode of operation  > ANNEX A  > 5-bit operational mode  > The 5-bit mode is defined in ANSI TIA/EIA-825 (2000), A Frequency Shift Keyed Modem for use on the Public Switched Telephone Network.  > > The communication channel is half-duplex with no channel turnaround. Carrier is transmitted 150 ms before the first character is transmitted. The receiver shall be disabled for 300 ms when a character is transmitted to mitigate false detection of echoes (in non-V.18 devices, the carrier may remain for up to 1 s after the last character to provide this same function).  > > A.2 Modulation  > The modulation is frequency shift-keyed modulation (i.e. no carrier is present when a character is not being transmitted) using 1400 Hz (±5%) for a binary 1 and 1800 Hz (±5%) for a binary 0. A bit duration of either 20 or 22.00 ± 0.40 ms is used providing either a nominal data signalling rate of 50 or 45.45 bits/s respectively.  Looking at our captured audio from the letter `A`, here's what we see: ![](https://cdn-learn.adafruit.com/assets/assets/000/090/764/medium800/hacks_breakdown.png?1588183605) - A bit is 20ms in duration - The lower frequency 1400Hz tone is used both as the carrier tone and to represent a binary `1` - The higher frequency 1800Hz tone is used to represent binary `0` - Letter `A` (see full chart below) has a binary 5-bit encoding of `00011` - 5-bit character codes are sent with in order of least signifigant bit (so "right-to-left"), which means the `A` bits are transmitted as `11000` - The start bit is a binary 0 sent for 1 bit time, while the stop bit is a binary 1 sent for at least 1.5 bit time Put all of that together and we get this: `carrier (for 150ms) + 0 + 11000 + 1 (for 40ms) `   Play the file below to hear the A audio looped five times. https://soundcloud.com/user-505776715/tty-5-bit-a ![](https://cdn-learn.adafruit.com/assets/assets/000/090/768/medium800/hacks_tty_chart.png?1588185239) One other important feature of the TTY 5-bit code is the implementation of character sets. With 5 bits we can only encode 32 characters, however there are two mode character codes reserved (sort of like a shift or control key) for switching the decoder between "letters" and "figures". When the LTRS mode character (`11111`) is sent, all characters that follow are decoded as their alphabet letter version. When the FIGS mode character (11011) is send, all characters that follow are decoded as their numerical or symbol variant. In practice: - `11111` + `01101` would decode as F - `11011` + `01101` would decode as ! The mode character should be sent right before any shift to the other mode, or every 72 characters even if you are staying in one mode. You'll notice these mode swaps when typing on a TTY machine because some keystrokes will suddenly sound twice as long as the mode character is sent right before the letter or figure character. Now, lets implement this in CircuitPython to send tones over a speaker and into the TTY system. # CLUE Text Telephone Transmitter ## CircuitPython on CLUE [CircuitPython](https://github.com/adafruit/circuitpython) is a derivative of [MicroPython](https://micropython.org) designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the **CIRCUITPY**  flash drive to iterate. The following instructions will show you how to install CircuitPython. If you've already installed CircuitPython but are looking to update it or reinstall it, the same steps work for that as well! ## Set up CircuitPython Quick Start! Follow this quick step-by-step for super-fast Python power :) [Download the latest version of CircuitPython for CLUE from circuitpython.org](https://circuitpython.org/board/clue_nrf52840_express/) **Click the link above to download the latest version of CircuitPython for the CLUE.** Download and save it to your desktop (or wherever is handy). ![adafruit_products_CLUE_UF2_Downloaded.png](https://cdn-learn.adafruit.com/assets/assets/000/088/037/medium640/adafruit_products_CLUE_UF2_Downloaded.png?1580840077) Plug your CLUE into your computer using a known-good USB cable. **A lot of people end up using charge-only USB cables and it is very frustrating! So make sure you have a USB cable you know is good for data sync.** Double-click the **Reset** button on the top (magenta arrow) on your board, and you will see the NeoPixel RGB LED (green arrow) turn green. If it turns red, check the USB cable, try another USB port, etc. **Note:** The little red LED next to the USB connector will pulse red. That's ok! If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right! ![adafruit_products_Clue_Reset_NeoPixel_bootloader.png](https://cdn-learn.adafruit.com/assets/assets/000/087/919/medium640/adafruit_products_Clue_Reset_NeoPixel_bootloader.png?1580496467) You will see a new disk drive appear called **CLUEBOOT**. Drag the **adafruit-circuitpython-clue-etc.uf2** file to **CLUE**** BOOT.** ![adafruit_products_CLUE_CLUEBOOT.png](https://cdn-learn.adafruit.com/assets/assets/000/088/042/medium640/adafruit_products_CLUE_CLUEBOOT.png?1580841287) ![adafruit_products_CLUE_drag_UF2.png](https://cdn-learn.adafruit.com/assets/assets/000/088/043/medium640/adafruit_products_CLUE_drag_UF2.png?1580841295) The LED will flash. Then, the **CLUEBOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear. If this is the first time you're installing CircuitPython or you're doing a completely fresh install after erasing the filesystem, you will have two files - **boot\_out.txt** , and **code.py** , and one folder - **lib** on your **CIRCUITPY** drive. If CircuitPython was already installed, the files present before reloading CircuitPython should still be present on your **CIRCUITPY** drive. Loading CircuitPython will not create new files if there was already a CircuitPython filesystem present. That's it, you're done! :) ![adafruit_products_CLUE_CIRCUITPY.png](https://cdn-learn.adafruit.com/assets/assets/000/088/044/medium640/adafruit_products_CLUE_CIRCUITPY.png?1580841453) # CLUE Text Telephone Transmitter ## Assemble the Transmitter ![](https://cdn-learn.adafruit.com/assets/assets/000/090/743/medium800/hacks_tty-2042.jpg?1588178434) To get a nice, clear audio output from the CLUE, we'll add an amplifier/speaker breakout board. The STEMMA Speaker board plus JST-to-alligator clips cable makes it easy. ## Hook Up Plug the JST 3-pin cable into the STEMMA Speaker board. It is keyed to only go in one way. Now, connect the three alligator clips to the CLUE board from the back side. Make these connections: - **white** to pin **#0** - **red** to pin **3V** - **black** to pin **GND** ![hacks_tty-2050.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/744/medium640/hacks_tty-2050.jpg?1588178636) ![hacks_tty-2049.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/745/medium640/hacks_tty-2049.jpg?1588178645) ![hacks_tty-2048.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/746/medium640/hacks_tty-2048.jpg?1588178652) If you are sending audio TTY transmissions over a phone line to a TTY machine on the other end of the line, you'll simply hold the STEMMA speaker to the mouthpiece of your phone handset. To test on a local machine (and see the text show up on the supremely awesome vacuum fluorescent display!) you can hold the speaker to the mic input coupler, or more permanently attach it with rubber bands as shown below. Wrap two rubber bands around the mouthpiece coupler on the TTY machine. Place the STEMMA speaker directly over the coupler stalk. Criss cross the rubber bands over the STEMMA speaker board to hold it snugly in place (the fewer unwanted mechanical vibrations the better). You may also use a single rubber band to hold the CLUE board onto the battery cover as shown. ![hacks_tty-2047.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/747/medium640/hacks_tty-2047.jpg?1588178887) ![hacks_tty-2046.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/748/medium640/hacks_tty-2046.jpg?1588178894) ![hacks_tty-2045.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/749/medium640/hacks_tty-2045.jpg?1588178901) ![hacks_tty-2044.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/750/medium640/hacks_tty-2044.jpg?1588178909) ![](https://cdn-learn.adafruit.com/assets/assets/000/090/757/medium800/hacks_tty-2043.jpg?1588179057) ## Power Most TTY machines can be powered from batteries or a DC 9V wall adapter. You can choose to power your CLUE from USB power or a battery, such as a LiPo or a small 3x AAA battery pack. ![hacks_IMG_2054.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/759/medium640/hacks_IMG_2054.jpg?1588179172) # CLUE Text Telephone Transmitter ## Code the TTY Transmitter https://youtu.be/z2ht4x-8qz4 ## Text Editor Adafruit recommends using the Mu editor for editing your CircuitPython code. You can get more info in [this guide](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor). Alternatively, you can use any text editor that saves files. ## Installing Project Code To use with CircuitPython, you need to first install a few libraries, into the lib folder on your **CIRCUITPY** drive. Then you need to update **code.py** with the example script. Thankfully, we can do this in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries and the **code.py** file in a zip file. Extract the contents of the zip file, open the directory **Baudot\_TTY/baudot\_tty/** and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your **CIRCUITPY** drive. Your **CIRCUITPY** drive should now look similar to the following image: ![CIRCUITPY](https://adafruit.github.io/Adafruit_Learning_System_Guides/Baudot_TTY_baudot_tty.png ) https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Baudot_TTY/baudot_tty/code.py Here's how the code works: ## Libraries First, we'll import the necessary libraries, including the audiocore RawSample and audiopwmio that allow us to create an play tones over the analog output pin. ```python import time import math import array import board from audiocore import RawSample import audiopwmio ``` ## Sine Waves Next we'll create some constants and code to generate a couple of sine wave tables, one at 1400Hz and the other at 1800Hz. ```python SIN_LENGTH = 100 # more is less choppy SIN_AMPLITUDE = 2 ** 12 # 0 (min) to 32768 (max) 8192 is nice SIN_OFFSET = 32767.5 # for 16bit range, (2**16 - 1) / 2 DELTA_PI = 2 * math.pi / SIN_LENGTH # happy little constant sine_wave = [ int(SIN_OFFSET + SIN_AMPLITUDE * math.sin(DELTA_PI * i)) for i in range(SIN_LENGTH) ] tones = ( RawSample(array.array("H", sine_wave), sample_rate=1800 * SIN_LENGTH), # Bit 0 RawSample(array.array("H", sine_wave), sample_rate=1400 * SIN_LENGTH), # Bit 1 ) ``` ## Lists We'll create a pair of lists called `LTRS` and `FIGS` that contain the full character sets we'll be able to send. We'll also set the `current_mode` to `LTRS` for purposes of sending the mode code and switching between the modes. ## Baudot Functions A series of functions are used to create the different uses of the sine waves for carrier tone, binary 0 bit, binary 1 bit, start bit, and stop bit. ```python def baudot_bit(pitch=bit_1, duration=0.022): # spec says 20ms, but adjusted as needed dac.play(pitch, loop=True) time.sleep(duration) # dac.stop() def baudot_carrier(duration=0.15): # Carrier tone is transmitted for 150 ms before the # first character is transmitted baudot_bit(carrier, duration) dac.stop() def baudot_start(): baudot_bit(bit_0) def baudot_stop(): baudot_bit(bit_1, 0.04) # minimum duration is 30ms dac.stop() ``` ## Send Character The `send_character()` function bundles up the parts into a proper TTY compliant message including the carrier tone, start bit, 5-bit character, stop bit, and carrier tone again. It receives a value argument of a 5-bit binary code from the LTRS or FIGS list and marches through this from LSB first, using bit shifting and bit masking to grab each relevant bit and convert it to the proper tone. ```python def send_character(value): baudot_carrier() # send carrier tone baudot_start() # send start bit tone for i in range(5): # send each bit of the character bit = (value >> i) & 0x01 # bit shift and bit mask to get value of each bit baudot_bit(tones[bit]) # send each bit, either 0 or 1, of a character baudot_stop() # send stop bit baudot_carrier() # not to spec, but works better to extend carrier ``` ## Send Message The `send_message()` function is a convenience function for bundling up a whole message string and then one at a time converting the characters to proper `send_character()` commands. This includes testing each character to see if it is a LTRS or FIGS list item, and then sending the proper mode character if needed. It also follows the spec and sends the relevant mode character after every 72 characters. ```python def send_message(text): global char_count, current_mode # pylint: disable=global-statement for char in text: if char not in LTRS and char not in FIGS: # just skip unknown characters print("Unknown character:", char) continue if char not in current_mode: # switch mode if current_mode == LTRS: print("Switching mode to FIGS") current_mode = FIGS send_character(current_mode.index("FIGS")) elif current_mode == FIGS: print("Switching mode to LTRS") current_mode = LTRS send_character(current_mode.index("LTRS")) # Send char mode at beginning of message and every 72 characters if char_count >= 72 or char_count == 0: print("Resending mode") if current_mode == LTRS: send_character(current_mode.index("LTRS")) elif current_mode == FIGS: send_character(current_mode.index("FIGS")) # reset counter char_count = 0 print(char) send_character(current_mode.index(char)) time.sleep(char_pause) # increment counter char_count += 1 ``` ## Main Loop The main loop of the program sends whatever messages are specified. In these demos the \n carriage return is used to add a break between messages. There is also a commented sample of sending a single character. ```python while True: send_message("\nADAFRUIT 1234567890 -$!+='()/:;?,. ") time.sleep(2) send_message("\nWELCOME TO JOHN PARK'S WORKSHOP!") time.sleep(3) send_message("\nWOULD YOU LIKE TO PLAY A GAME?") time.sleep(5) # here's an example of sending a character # send_character(current_mode.index("A")) # time.sleep(char_pause) ``` # CLUE Text Telephone Transmitter ## Code the BLE TTY Transmitter https://youtu.be/vsi7gwKwP-U After trying the simple example on the previous page, you can switch to this code to try out Bluetooth LE functionality using the Adafruit Bluefruit LE Connect app on your iOS or Android device. [See this guide](https://learn.adafruit.com/bluefruit-le-connect) to get the app installed and set up. ## Installing Project Code To use with CircuitPython, you need to first install a few libraries, into the lib folder on your **CIRCUITPY** drive. Then you need to update **code.py** with the example script. Thankfully, we can do this in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries and the **code.py** file in a zip file. Extract the contents of the zip file, open the directory **Baudot\_tty/baudot\_tty\_ble/** and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your **CIRCUITPY** drive. Your **CIRCUITPY** drive should now look similar to the following image: ![CIRCUITPY](https://adafruit.github.io/Adafruit_Learning_System_Guides/Baudot_TTY_baudot_tty_ble.png ) https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Baudot_TTY/baudot_tty_ble/code.py Once you've copied the **code.py** code file to your CLUE, you can connect from the Bluefruit app to the CLUE device named TTY Machine and then use the UART function to send messages to the CLUE. The letters will be received by the CLUE and then sent as audio to the TTY machine! # CLUE Text Telephone Transmitter ## Code the TTY GUI https://youtu.be/3iv9o4jm3sk This version of the code adds in a simple GUI for selecting a phrase with the A button and sending it with the B button. ![](https://cdn-learn.adafruit.com/assets/assets/000/090/796/medium800/hacks_IMG_2059.jpg?1588211706) ## Installing Project Code To use with CircuitPython, you need to first install a few libraries, into the lib folder on your **CIRCUITPY** drive. Then you need to update **code.py** with the example script. Thankfully, we can do this in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries and the **code.py** file in a zip file. Extract the contents of the zip file, open the directory **Baudot\_TTY/baudot\_tty\_gui/** and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your **CIRCUITPY** drive. Your **CIRCUITPY** drive should now look similar to the following image: ![CIRCUITPY](https://adafruit.github.io/Adafruit_Learning_System_Guides/Baudot_TTY_baudot_tty_GUI.png ) https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Baudot_TTY/baudot_tty_GUI/code.py ## Featured Products ### Adafruit CLUE - nRF52840 Express with Bluetooth® LE [Adafruit CLUE - nRF52840 Express with Bluetooth® LE](https://www.adafruit.com/product/4500) Do you feel like you just don't have a CLUE? Well, we can help with that - get a CLUE here at Adafruit by picking up this sensor-packed development board. We wanted to build some projects that have a small screen and a lot of sensors. To make it compatible with existing projects, we made... In Stock [Buy Now](https://www.adafruit.com/product/4500) [Related Guides to the Product](https://learn.adafruit.com/products/4500/guides) ### Adafruit STEMMA Speaker - Plug and Play Audio Amplifier [Adafruit STEMMA Speaker - Plug and Play Audio Amplifier](https://www.adafruit.com/product/3885) Hey, have you heard the good news? With Adafruit STEMMA boards you can easily and safely plug sensors and devices together, like this **Adafruit STEMMA Speaker - Plug and Play Audio Amplifier**. Like the name implies, it's got a class D audio amplifier on board, and our... In Stock [Buy Now](https://www.adafruit.com/product/3885) [Related Guides to the Product](https://learn.adafruit.com/products/3885/guides) ### USB cable - USB A to Micro-B [USB cable - USB A to Micro-B](https://www.adafruit.com/product/592) This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller Approximately 3 feet / 1 meter long In Stock [Buy Now](https://www.adafruit.com/product/592) [Related Guides to the Product](https://learn.adafruit.com/products/592/guides) ## Related Guides - [Adafruit STEMMA Speaker](https://learn.adafruit.com/adafruit-stemma-speaker.md) - [Introducing Adafruit CLUE](https://learn.adafruit.com/adafruit-clue.md) - [Circuit Playground Bluefruit Pumpkin with Lights and Sounds ](https://learn.adafruit.com/pumpkin-with-circuit-playground-bluefruit.md) - [CLUE Slim Case](https://learn.adafruit.com/clue-slim-case.md) - [Adafruit Bonsai Buckaroo](https://learn.adafruit.com/adafruit-bonsai-buckaroo.md) - [A colorful CLUE slideshow purse with Bright Wearables](https://learn.adafruit.com/a-colorful-clue-slideshow-purse.md) - [RGB Matrix Dreidel Game](https://learn.adafruit.com/rgb-matrix-dreidel-game.md) - [CLUE Light Paint Stick with CircuitPython](https://learn.adafruit.com/clue-light-paintstick.md) - [CLUE Sensor Plotter in CircuitPython](https://learn.adafruit.com/clue-sensor-plotter-circuitpython.md) - [AdaBox 015](https://learn.adafruit.com/adabox015.md) - [Chauncey the Flower Care Bot with CLUE and Bonsai Buckaroo](https://learn.adafruit.com/chauncey-flower-watering-bot-clue.md) - [Which CircuitPython Board is Right for You?](https://learn.adafruit.com/choose-your-circuitpython-board.md) - [Creative Inspiration Activity Generator](https://learn.adafruit.com/creative-inspiration-activity-generator.md) - [Bluetooth LE Sensor Nodes to Raspberry Pi WiFi Bridge](https://learn.adafruit.com/bluetooth-le-broadcastnet-sensor-node-raspberry-pi-wifi-bridge.md) - [MIDI for Makers](https://learn.adafruit.com/midi-for-makers.md) - [Digital Egg Drop Experiment with CLUE](https://learn.adafruit.com/egg-drop-clue.md) - [CLUE Step Counter](https://learn.adafruit.com/clue-step-counter-st-lsm6ds33.md)