verified for Debian 11 (bullseye) and Debian 12 (bookworm) and the corresponding Raspberry Pi OS versions

• Download and install the tool raspberrypi imager from https://raspberrypi.com/software. It is available for Windows, linux and Mac.

• Download and flash the OS image to a MicroSD-Card (min. 8GB) using the raspberry pi imager. See here for details.

• Boot the RPi from this freshly flashed µSD-Card (First boot will take its time, so stay relaxed...)

• Log in to your RPi via secure shell:

  • linux systems: ssh <user>@<hostname>

  • windows systems: use e.g. program putty as terminal software for logging in via ssh

  Use <hostname> and <user> as well as the password as configured at flashing time (default user is pi, see above).

• Set Raspberry Options

  Logged in to the RPi, use sudo raspi-config to set the following remaining options:

  • Menu "Interface options":
    • Disable SPI
  • Menu "System":
    • Enable Wait for network at boot
  • Menu "Localisation Options":
    • Generate locales as needed

  $ sudo apt update
  $ sudo apt upgrade
  $ sudo shutdown -r now

• Be sure that Python 3 is installed:

  $ sudo apt -y install python3

• Python lib commentjson allows comments in the configuration file (not mandatory but VERY useful :-) )

  $ sudo apt -y install python3-commentjson

​

• Install GPIO libs

  $ sudo apt -y install python3-pigpio

• Start pigpio daemon (Raspberry Pi only)

  $ sudo systemctl start pigpiod

• Check if daemon is running: (Raspberry Pi only)

  $ sudo systemctl status pigpiod

  should say "running"...

• Enable pigpio daemon to start at boot: (Raspberry Pi only)

  $ sudo systemctl enable pigpiod

• Install additional python lib for serial communications

  $ sudo apt -y install python3-serial

• Install python libs for handling FSK

  $ sudo apt -y install python3-numpy python3-scipy python3-pyaudio

There are two methods to download and install the piTelex software.

• Release Archives are statically packed and tested snaphots of the github repository. This ensures a definite software version which only contains the well known bugs :-) The archives are ZIP files and are named <year>-<month>.zip, e.g. 2025-02.zip

• Github provides access to the development repositories of piTelex. Here you can obtain the very latest versions of piTelex, but on the other hand, there is a risk to download also the very latest bugs :-)

Decide for yourself...

• As user pi, download the desired (probably the latest) release archive from https://github.com/fablab-wue/piTelex/releases and extract it in the home directory. This will put the complete software tree in a directory piTelex-<year>-<month> in your home directory. Then rename piTelex-year>-<month> to piTelex, as piTelex assumes it's home in $HOME/piTelex.

  $ cd
  $ wget https://github.com/fablab-wue/piTelex/archive/refs/tags/<year>-<month>.zip
  $ unzip <year>-<month>.zip
  $ mv piTelex-<year>-<month> piTelex

• Install git

  $ sudo apt -y install git

• Clone the github repository as normal user pi, i.e. without sudo ...

  $ cd  
  $ git clone -b master https://github.com/fablab-wue/piTelex.git

  This will put the complete software tree (stable version) in a directory piTelex in your home directory.

  [!NOTE] To clone a different branch, just change masterto the name of the desired branch.

• Make the python file executable

  $ cd ~/piTelex
  $ chmod +x telex.py

• Then try to start telex as normal user (i.e. without sudo):

  $ ./telex.py 

  Ideally, your terminal will present you a freshly blanked screen and after some seconds a line

  **-=TELEX=-**

  and a prompt. If this happens: congratulations! Sit back and go for a cup of coffee... But maybe either nothing happens, or you encounter a bunch of error messages.

  Don't give up :-)

  It is very likely that piTelex' initial standard configuration doesn't meet your environment. With luck, it is sufficient to select the correct mode by specifying command line arguments, but in most cases it will be necessary to edit the configuration file to reflect your needs:

  $ cd ~/piTelex
  $ nano telex.json

  [!NOTE]

  Nano is a common text editor in linux, but any other will do (emacs, vi, joe, ...).

  [!TIP]

  It is strongly recommended to read the section on Configuration of your system beforehand, for piTelex offers an overwhelming wealth of configuration options. Sit back and go for a cup of coffee...

  In the meantime you may stop piTelex with Ctrl-C (possibly twice) or by entering <ESC>exit<Enter> .

  If the trouble persists, consult the Debugging section for further tips.

• Install a Python interpreter with version 3.5 or higher (e.g. Anaconda)

• Download source from https://github.com/fablab-wue/piTelex.git as zip file

• Expand the zip file to your disk (e.g. C:\piTelex)

• Start a command prompt (or Anaconda prompt) as administrator

• Install python dependencies:

  pip install commentjson

  • If using USB-Serial-Adapter (TW39, TWM and V.10) additionally install:

        pip install pyserial
    

  • If using USB-Sound-Card (ED1000) additionally install:

        pip install pyaudio numpy scipy
    

• Start a command prompt (or Anaconda prompt) as normal user

• Navigate to the piTelex directory:

  cd \piTelex
  

• Start program:

  python telex.py <args>
  

Ideally, your terminal will present you a freshly blanked screen and after a couple of seconds a line "-=TELEX=-" and a flashing prompt. If this happens, sit back and go for a cup of coffee 🥇 . But chances are that you will encounter a bunch of error messages. Don't give up :-) piTelex isn't configured yet to meet your hardware environment. You may try to select the correct mode by specifying command line arguments, but really fine grained control can only be achieved by editing the configuration file to reflect your needs. Now it's time to read the pages about the Configuration of your system. If the trouble persists, consult the Debugging section for further tips.

In the meantime you may

• Stop piTelex with Ctrl-C (possibly twice) or by entering <ESC>exit<Enter>