verified for Raspberry Pi OS bullseye and bookworm

• Download 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 download tool. 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.

• 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

Alternative step by step installation method: step by step (not really recommended, but nevertheless cool ...)

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

• Python 3 should be already installed by default; if not, install it manually:

  $ sudo apt -y install python3
  

• Python lib commentjson allows comments in the configuration file

  $ sudo apt -y install python3-commentjson
  

• Install GPIO libs (Raspberry Pi only)

  $ 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
  

• Install github

  $ sudo apt -y install git
  

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

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

  This will put the complete software tree in a directory piTelex in your home directory.

• Download the desired zip- or tar.gz-Archive from https://github.com/fablab-wue/piTelex/releases and extract it to the home directory of user pi:

     $ cd; unzip /path/to/<releasefile.zip> 
  

  --or--

     $ cd; tar xfvz /path/to/<releasefile>.tar.gz
  

  This ends up with a subdirectory piTelex-<release> containing the complete piTelex software.

• Rename piTelex-<release> to piTelex or put a link to it:

    $ mv piTelex-<release> piTelex
  

  --or--

    $ ln -s piTelex-<release> piTelex
  

• Make the python file executable

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

• Now check and adapt the settings in telex.json (according to the section "Configuration"). 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 :-)

  Chances are that piTelex' configuration still doesn't 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 in detail. 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>

• 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>