SW_Install

Software Installation

Debian based Linux systems including Raspberry Pi OS

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

Caution

Up to now, the 64bit version of Raspberry Pi OS trixie does NOT support the use of the GPIO lines out of the box! Either use the 32bit version or go back to RPi OS 12 (bookworm based) See here for details.

Important

The instructions below assume that you have set the default user for piTelex to be pi and thus have also set the default home directory to /home/pi. For different user names or path specs, the values must be adjusted accordingly!

1. Install the OS (Raspberry Pi only):

• 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

  • or via USB-Keyboard and Monitor :-)

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

2. Update your OS:

• Update the apt database, then upgrade. Finally, reboot your system

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

3. Install required software:

• Ensure that Python 3 is installed:

  $ sudo apt install python3

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

  $ sudo apt -y install python3-commentjson

​

4. Optional prerequisites

a) RaspBerry Pi: only if GPIO lines will be used to control piTelex' hardware:

Warning

There are reports that the pigpio package is no longer available under trixie (see https://github.com/joan2937/pigpio/issues/632).

The 32-bit version is apparently not affected and can be installed and used normally. For the 64-bit version, please follow the workaround instructions in the above link.

A ready-to-run 32-bit trixie image of Pi OS lite with preinstalled piTelex (latest release 2025-06) can be downloaded from e.g. https://github.com/rwobrecht/piTelex-contrib/tree/main/soft (german language).

• Install GPIO libs

  $ sudo apt -y install python3-pigpio

• Start pigpio daemon

  $ sudo systemctl start pigpiod

• Check if daemon is running:

  $ sudo systemctl status pigpiod

  should say "running"...

• Enable pigpio daemon to start at boot:

  $ sudo systemctl enable pigpiod

b) All platforms: only if module CH340 is to be used to control piTelex' hardware:

• Install additional python lib for serial communications

  $ sudo apt -y install python3-serial

c) All platforms: only if module ED1000 is to be used to control piTelex' hardware:

• Install python libs for handling FSK

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

Note

The software dependencies listed here are sufficient for "normal" piTelex use. More specific piTelex modules may require further python packages which are listed on the resp. module page.

5. Download and install piTelex

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

a) Using a release archive

Release archives are statically packed and tested snapshots 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

• 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

b) Using git

Git 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 :-)

• First install git, then clone the repository as user pi into your home directory. If you want to download a branch other than the master branch, replace ‘master’ with the name of the desired branch.

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

6. Finalize the installation

• Ensure that the main python file is 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 like:

  -= TELEX (Rev. 001d 2025-05-20 13:36) =-

  and a cursor. 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.

---

PC-Windows

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

• Download the desired (probably the latest) release archive (zip file) from https://github.com/fablab-wue/piTelex/releases and extract it to disk. This will put the complete software tree in a directory piTelex-<year>-<month> . Then rename piTelex-year>-<month> to piTelex, as piTelex assumes it's home in 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 (assuming \piTelex):

  cd \piTelex 
  

• Start program:

  python telex.py
  

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

  -= TELEX (Rev. 001d 2025-05-20 13:36) =-

  and a cursor. 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.

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.