µracoli Manual  Version foo
uracoli-sterm.md
1 # sterm - A Scriptable Terminal {#md_sterm}
2 
3 * Author: Axel Wachtler
4 * Date: 2010/07 - 2015/03
5 
6 ## Abstract
7 
8 While developping and debugging wireless applications, it is usefull to connect
9 two or more nodes via a serial interface with a PC in order to watch and analyze
10 the debugging output. The programm sterm.py is (yet another) terminal application
11 written in Python/TKinter, that provides this multiport feature.
12 
13 ## Prerequisites
14 
15 In order to run `sterm.py` an installed version of http://www.python.org[Python]
16 (required is version 2.x but *not* 3.x) and the module `pyserial` is needed.
17 A short decription how to install and upgrade Python on your PC
18 can be found under
19 http://uracoli.nongnu.org/gettingstarted.html#_installing_and_upgrading_python[Installing and Upgrading Python].
20 If you will use a transceiver board with an USB interface, of course the correct
21 USB driver must be loaded.
22 
23 ## Running sterm.py
24 
25 The program `wuart/sterm.py` is simply started by the command:
26 
27  python sterm.py
28 
29 If the configuration file `sterm.cfg` is not found in the current directory,
30 a default version of this file is created and must be modified, to reflect your
31 configuration.
32 
33 With the command `python sterm.py -h` a list of available command line options
34 is displayed.
35 
36  Usage:
37  python sterm.py [OPTIONS]
38 
39  Options:
40  -h, --help
41  show this help message
42  -v, --version
43  show version number
44  -c FILE, --config FILE
45  load config file, default value `sterm.cfg`
46  if FILE is not existing, an annotated version
47  is generated and the tool is exited.
48 
49 ## Configuring sterm.py
50 
51 ### Overview
52 
53 The setup is configured with the file `sterm.cfg`. This file is written in
54 WIN.INI format and consists of the following sections.
55 
56  `[sterm.py]`::
57  The section name "CONFIG" is reserved for the global configuration of
58  `sterm.py`.
59  `[mydevice]`::
60  A device section defines the serial port settings and
61  other configuration parameters. It can have a arbitary but
62  unique (within `sterm.cfg`) name.
63  `[mymacro]`::
64  A macros section defines either a text or a smart macro.
65  It can have a arbitary but unique (within `sterm.cfg`) name.
66 
67 
68 ### The `[sterm.py]` Section
69 
70 The CONFIG section holds the global configuration information.
71 
72  [sterm.py]
73  devices = .... list of enabled devices
74  plugins = .... list of files with smart macro functions
75  macros = .... macros enable globally for all devices
76 
77 ### The `[Device]` Section
78 
79 The example file `sterm.cfg` defines three devices:
80 coord, dev1, dev2, dev3. Each devices is described within a configuration
81 section, which has the following contents:
82 
83  [coord]
84  type = serial
85  port = /dev/ttyS4
86  baudrate = 9600
87  logname = coord.log
88  logmode = w
89  echo = 1
90  log = 1
91  connect = 1
92  macros = mycommand_01 mycommand_02
93 
94 
95 The entries have the following meaning:
96 
97  - type: currently only value "serial" is usefull.
98  - port: the name of the serial port, under Windows probably COMx
99  - baudrate: the serial baudrate to be used (in bit/s, e.g. 9600, 19200, 57600)
100  - logname: name of the generated logfile
101  - logmode: "a" for append to the file or "w" to write file from start
102  - log: a 1 means that writing to the logfile is enabled right at startup,
103  a 0 means that you need to click the "log" button to open the logfile.
104  - echo: 1 local terminal echo is enabled at startup
105  - connect: 1 means that the serial connection is opened at programm startup
106  - macros: list of macros for this device.
107 
108 
109 After defining a device, it needs to be listed in the "[CONFIG]" section in the
110 keyword "devices", e.g.
111 
112  [sterm.py]
113  devices = coord dev1 dev2 dev3
114  ....
115 
116 ### The `[Macro]` Section
117 
118 The program sterm.py provides two types of macros: a) normal text macros and b)
119 smart macros, which are implemented by python functions.
120 
121 Here are two examples for a text macros:
122 
123  [qbf]
124  text = The quick brown fox jumps over the lazy dog.
125 
126  [peli]
127  text = A wonderful bird is the pelican,
128  His bill will hold more than his belican,
129  He can take in his beak
130  Enough food for a week
131  But I'm damned if I see how the helican!
132 
133 The "qbf" macro sends a single line to the serial device and the "peli" macro
134 sends multiple lines to the serial device.
135 
136 Smart macros are configured by the keywords "function" and "params".
137 The "function" keyword holds the name of a function that is defined in a
138 plugin file. The "params" keyword is a python expression that creates a
139 parameter dictionary the function is called with.
140 
141  [mycommand_01]
142  function = mycommand
143  params = dict(nbdevices = 1, channel = 0, chanpg=5, test=3)
144 
145 ### Assigning Macros
146 
147 The macros are buried behind the button "Macros" as a drop down list. The
148 macro assignement can be global in the "[CONFIG]" section or local in the
149 "[mydevice]" device specification section.
150 
151 Here are two assignment examples:
152 
153  [sterm.py]
154  devices = coord dev1 dev2 dev3
155  plugins = plugin.py
156  macros = qbf
157 
158  [mydevice]
159  type = serial
160  ....
161  macros = mycommand_01
162 
163 The macro "qbf" is assigned globally to all defined devices, where the macro
164 "mycommand_01" is just assinged to the device "mydevice".
165 
166 ### Using Smart Macros
167 
168 #### Writing Smart Macros
169 
170 Smart Macros are implemented by a python function. Here is an example:
171 
172 ~~~~~~~~~~~~~~~~~~~~~~{.PY}
173 import time
174 def mycommand(devices, nbdevices, test, channel, chanpg, pan = 1):
175  print "test=%d, channel=%d, chanpg=%d, test=%d, pan=%d" % \
176  (test, channel, chanpg, test, pan)
177  cmd = "%02d%02d%1d%02d" % (channel, chanpg, pan, test)
178  print "Run: %s" % cmd
179  devices['coord'].write("Sc%s" % cmd)
180  if nbdevices >=1:
181  time.sleep(1)
182  devices['dev1'].write("S1%s" % cmd)
183  if nbdevices >=2:
184  time.sleep(1)
185  devices['dev2'].write("S2%s" % cmd)
186  if nbdevices >=3:
187  time.sleep(1)
188  devices['dev3'].write("S3%s" % cmd)
189 ~~~~~~~~~~~~~~~~~~~~~~
190 
191 The first parameter "devices" of the function `mycommand()` holds a dictionary of
192 all defined serial devices. By means of the device function "write" the smart
193 macro function can send data to all available devices. All other parameters
194 (e.g. nbdevices, test, channel, chanpg, pan = 1) are function specific and given
195 by the `params` keyword in the configuration file.
196 
197 #### Loading Smart Macros
198 
199 Smart macros are loaded in the "[sterm.py]" section of the config file just by
200 writing the file name (with a path component) behind the keywords "plugins".
201 
202  [sterm.py]
203  ...
204  plugins = plugin.py
205  ...
206