SW_ConfigJSON

Configuration file

piTelex main configuration tool is a text file in JSON format, editable by any text editor of your choice. It's default name is telex.jsonand it is by default located in the piTelex directory. Path and file name can be overriden by command line parameter -c / --config.

All configuration entries are optional (with one exception: see devices section). Missing parameters will be substituted by their defaults, as listed here and in the respective module description.

If commentjson is installed, the file may contain comments according to commentjson-rules; otherwise, an error will be thrown when pitelex starts up.

The order of the device sections as well as the order of the entries within a section do not matter.

Important

Invalid entries ( e.g. unknown parameters, mis-typed entries) are ignored without warning.

Note

Remember to restart piTelex when the configuration file has been altered. piTelex reads the file only at startup.**

Devices section

The file consists of a mandatory dictionary of devices which are under control of piTelex, followed by an (optional) global section containing some steering variables / settings. The device dictionary object has the name devices{}.

Each device definition herein is again a named JSON object; the device names can be chosen freely, e.g. myFavouriteTeletypeor whatever name you prefer. It is however common practice to give the devices the names of the corresponding modules, as long as there is no conflict with other definitions.

Furthermore, there are two mandatory properties for each device:

• type : <ModuleName> points to the corresponding software module for the device
• enabled : true | false determines wether piTelex recognizes the device entry or not

followed by module-specific configuration parameters as explained in the Summary of Config Params and the respective module description.

Global section

The global section that follows the device definitions consists of the following directives:

Parameter	Default	Values	Description
errorlog_path	error_log	string	Directory path for error log
errorlog_level	"INFO"	"NOTSET", "DEBUG", "INFO", "WARN", "ERROR", "CRITICAL"	verbosity of error log (see python manual)
wru_id	[none]	string	Software-WRU-ID
wru_replace_always	false	false / true	if true, always replace Hardware-WRU by Software-WRU
continue_with_no_printer	true	false / true	if true, ignore missing / faulty printer device; if false, abort connections if teleprinter fails to start up
power_off_delay	20	non-neg. int	time in seconds from end-of-conection until switching off TTY power
power_button_timeout	300	non-neg. int	time in seconds from switching on TTY power by means of button PT until switch off PWR
dial_timeout	2.0	'+‘ / float (0.0...55.0)	idle time after last dialled digit to start dial process; if ‚+‘, „plus-dialling“ selected, if ‚0‘, instant dialling is used (see note below)

Answerback unit

If your teleprinter has a functional answerback unit, you should leave wru_id empty and wru_replace_always set to false. But some devices lack such a unit, and piTelex can cope with this, providing a software driven solution. In these cases, set wru_idto the correct value, e.g. wru_id : "123456 telex d" and enable the software answerback by setting wru_replace_always : true.

With wru_id configured and wru_replace_always : false piTelex first gives the teletype a chance to deliver its hardware answerback; if this doesn't succeed within a few seconds, the software id will be sent instead.

Printer state

piTelex also monitors the state of the teleprinter and terminates a connection if the teleprinter doesn't start up correctly. This is in order to avoid lost messages that have been transmitted but not printed because of a faulty printer. Some devices don't communicate the state of the printer properly. With such a device, try to set continue_with_no_printer : true . This will stop piTelex from watching the printer's state and continues the connection despite the incorrect state transitions.

Dialing

• Instant dialling is the classic dial method used in older piTelex versions. It's selected if the configured timeout is 0. In contrast to the other methods, dialling is tried after every entered digit, i.e. incrementally.

• Timeout dialling behaviour is based on i-Telex r874 (as documented in the comments at trunk/iTelex/iTelex. :4586) and simplified:

  1. After each digit, the local user list is searched in i-Telex. In piTelex, we don't, because in the current architecture it would complicate things quite a bit.
  2. TNS server is queried if at least five digits have been dialled and no further digit is dialled for two seconds.
  3. If there is a positive result from a local or TNS query, try to establish a connection.
  4. Dialling is cancelled if a connection attempt in 3. failed or if nothing further is dialled for 15 seconds.

• Plus dialling simply waits for digits, cumulates them and dials after '+' has been entered.

piTelex provides a local dictionary where you can store speed dials and only locally available machines which are not registered at the TNS. A sample file is located in piTelex' home directory, called userlist_example.csv. To make use of a local directory, edit the file to your needs and save it as userlist.csv in piTelex' home directory. Local entries take precedence over TNS server replies.

Minimalistic example

Let's say we just want to connect a Teletype over GPIO pins of a Raspberry Pi and 'chat' with it using the computers screen and keyboard, we need two modules, screen and RPiTTY. Our first telex.json might look like this:

    {
      # devices section
      "devices": {
        "Computerscreen": {
          "type": "screen",
          "enable": true
        },`
        "Teleprinter": {
          "type": "RPiTTY",       # Module name
          "enable": true,         # switch it on
          "pin_txd": 17,          # GPIO# for transmitted data
          "pin_rxd": 18,          # GPIO# for received data
          "baudrate": 50,         # speed
          "coding": 0             # Teleprinter uses ITA code
        },
        "messages": {
          "type": "log",         # logfile is available
          "enable": false,       # but disabled at the moment, maybe useful later...
          "filename": "test.log"
        },
      }
      # global directives
      "errorlog_path" : "local_errlog_dir"
    }

The third device messages configures and provides logging to a file. Logging can be simply switched on or off by altering the "enable"-parameter. This shows that you can have many more device entries in the configuration file, but piTelex will use only the "enabled" ones. A full blown example with further comments and explanations can be found in the code repository.

In section Devices the available device modules are described in detail.