TODO: mention some of the known issues in the TODO list
[SaveMySugar/python3-savemysugar.git] / src / savemysugar / CallDistanceTransceiver.py
1 #!/usr/bin/env python3
2 #
3 # CallDistanceTransceiver - send and receive Morse using phone calls distance
4 #
5 # Copyright (C) 2015  Antonio Ospite <ao2@ao2.it>
6 #
7 # This program is free software: you can redistribute it and/or modify
8 # it under the terms of the GNU General Public License as published by
9 # the Free Software Foundation, either version 3 of the License, or
10 # (at your option) any later version.
11 #
12 # This program is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15 # GNU General Public License for more details.
16 #
17 # You should have received a copy of the GNU General Public License
18 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
19
20
21 # This hack allows MorseTranslator to be imported also when
22 # __name__ == "__main__"
23 try:
24     from .MorseTranslator import MorseTranslator
25 except SystemError:
26     from MorseTranslator import MorseTranslator
27
28 import logging
29 import time
30
31
32 class SymbolTime(object):
33     """
34     In theory the symbol distance (the distance to discriminate symbols) can
35     be arbitrary, and it's only bounded below by the stability of the period
36     time, but in practice it can be necessary to wait a predefined minimum
37     amount of time between periods because of technological limits of the
38     transmitting devices, we call this time the "minimum inter-symbol
39     distance".
40     """
41
42     # pylint: disable=too-few-public-methods
43     def __init__(self, period_min, period_max, multiplier,
44                  min_inter_symbol_distance=0.0):
45         assert multiplier >= 0
46         if (period_min == period_max) and (min_inter_symbol_distance == 0):
47             raise ValueError("If (period_min == period_max) a non-zero",
48                              "inter-symbol distance MUST be specified")
49
50         symbol_distance = 2 * (period_max - period_min)
51         if symbol_distance == 0:
52             symbol_distance = min_inter_symbol_distance
53
54         # The time the transmitter has to wait to disambiguate between this
55         # symbol and a different one.
56         self.dist = min_inter_symbol_distance + symbol_distance * multiplier
57
58         # The minimum time which represents the symbol at the receiving end.
59         self.min = min_inter_symbol_distance + period_min + \
60             symbol_distance * multiplier
61
62         # The maximum time which represents the symbol at the receiving end
63         self.max = min_inter_symbol_distance + period_min + \
64             symbol_distance * (multiplier + 1)
65
66
67 class MorseDistanceModulator(object):
68     def __init__(self, period_min, period_max, pulse_min, pulse_max,
69                  inter_symbol_distance):
70         self.set_parameters(period_min, period_max,
71                             pulse_min, pulse_max,
72                             inter_symbol_distance)
73
74     def set_parameters(self, period_min, period_max, pulse_min, pulse_max,
75                        inter_symbol_distance):
76         self.period_min = period_min
77         self.period_max = period_max
78         self.pulse_min = pulse_min
79         self.pulse_max = pulse_max
80         self.inter_symbol_distance = inter_symbol_distance
81
82         self.dot_time = SymbolTime(period_min,
83                                    period_max, 0,
84                                    inter_symbol_distance)
85         self.dash_time = SymbolTime(period_min,
86                                     period_max, 1,
87                                     inter_symbol_distance)
88         self.signalspace_time = SymbolTime(period_min,
89                                            period_max, 2,
90                                            inter_symbol_distance)
91         self.wordspace_time = SymbolTime(period_min,
92                                          period_max, 3,
93                                          inter_symbol_distance)
94         self.eom_time = SymbolTime(period_min,
95                                    period_max, 4,
96                                    inter_symbol_distance)
97
98     def symbol_to_distance(self, symbol):
99         if symbol == ".":
100             return self.dot_time.dist
101         elif symbol == "-":
102             return self.dash_time.dist
103         elif symbol == " ":
104             return self.signalspace_time.dist
105         elif symbol == "/" or symbol == " / ":
106             return self.wordspace_time.dist
107         elif symbol == "EOM":
108             return self.eom_time.dist
109
110         raise ValueError("Unexpected symbol %s" % symbol)
111
112     def is_same_period(self, distance):
113         return distance > self.pulse_min and distance <= self.pulse_max
114
115     def distance_to_symbol(self, distance):
116         if distance > self.dot_time.min and \
117            distance <= self.dot_time.max:
118             return "."
119
120         if distance > self.dash_time.min and \
121            distance <= self.dash_time.max:
122             return "-"
123
124         if distance > self.signalspace_time.min and \
125            distance <= self.signalspace_time.max:
126             return " "
127
128         if distance > self.wordspace_time.min and \
129            distance <= self.wordspace_time.max:
130             return "/"
131
132         if distance > self.eom_time.min:
133             return "EOM"
134
135         raise ValueError("Unexpected distance %.2f" % distance)
136
137     def modulate(self, morse):
138         signals = morse.split(' ')
139         distances = []
140         for i, signal in enumerate(signals):
141             for symbol in signal:
142                 distances.append(self.symbol_to_distance(symbol))
143
144             # Transmit a signal separator only when strictly necessary.
145             #
146             # Avoid it in these cases:
147             #  - after the last symbol, because EOM is going to ne transmitted
148             #    anyway and that will mark the end of the last symbol.
149             #  - between words, because the word separator act as a symbol
150             #    separator too.
151             if i != len(signals) - 1 and signals[i + 1] != "/" and signal != "/":
152                 distances.append(self.symbol_to_distance(" "))
153
154         distances.append(self.symbol_to_distance("EOM"))
155
156         # Since the Morse signals are encoded in the distance between calls, an
157         # extra call is needed in order for receiver actually get the EOM and
158         # see that the transmission has terminated.
159         distances.append(0)
160
161         return distances
162
163
164 def log_symbol(distance, symbol, extra_info=""):
165     logging.info("distance: %.2f Received \"%s\"%s", distance, symbol,
166                  extra_info)
167
168
169 class CallDistanceTransceiver(object):
170     """Transmit Morse messages using the distance between calls.
171
172     This is basically a pulse-distance modulation (PDM).
173
174     A RING is a pulse and the Morse symbols are encoded in the pause between
175     the first ring of the previous call and the first ring of a new call.
176
177     This strategy is very slow but it can even be used with ancient analog
178     modems which don't have call progress notifications for outgoing calls, and
179     make it also hard to count multiple rings in the same call on the receiving
180     side because there is no explicit notification on the receiving side of
181     when the caller ends a calls.
182
183     For GSM modems, which have a more sophisticate call report signalling,
184     a more efficient encoding can be used (for example using ring counts to
185     encode Morse symbols, i.e. a pulse-length modulation), but for
186     a proof-of-concept, a slow encoding covering the most general setup is
187     fine.
188
189     Plus, supporting communications between analog modems is cool :)
190     """
191
192     def __init__(self, modem,
193                  call_setup_time_min=7, call_setup_time_max=15,
194                  ring_time_min=4.8, ring_time_max=5.2,
195                  add_inter_call_distance=True):
196         """Encode the Morse symbols using the distance between calls.
197
198         Args:
199
200             call_setup_time_min: the minimum time between  when the transmitter
201                 dials the number and the receiver reports RING notifications.
202             call_setup_time_max: the maximum time between when the transmitter
203                 dials the number and the receiver reports RING notifications.
204                 Waiting this time after dialing ensures that the receiver has
205                 received _at_least_ one ring. The default chosen here have been
206                 tested to work fine with old analog modems, provided that there
207                 is some more distance between two calls, and with Android
208                 receivers.
209             ring_time_min: the minimum time between two consecutive RINGs
210                 in the same call.
211             ring_time_max: the maximum time between two consecutive RINGs
212                 in the same call, the standard interval is about 5 seconds, but
213                 line and/or software delays can make it vary.  This is needed
214                 in order to ignore multiple ring in the same call when multiple
215                 RING in the same call are notified, and then be able to
216                 discriminate between two different calls.
217             add_inter_call_distance: specify if it is needed to wait an extra
218                 fixed time between calls.
219             """
220
221         self.modem = modem
222         self.translator = MorseTranslator()
223
224         self.call_setup_time_max = call_setup_time_max
225
226         if add_inter_call_distance:
227             # Analog modems don't like to dial a new call immediately after
228             # they hung up the previous one; an extra delay of about one
229             # ring time makes them happy.
230             inter_symbol_distance = ring_time_max
231         else:
232             inter_symbol_distance = 0
233
234         self.modulator = MorseDistanceModulator(call_setup_time_min,
235                                                 call_setup_time_max,
236                                                 ring_time_min,
237                                                 ring_time_max,
238                                                 inter_symbol_distance)
239
240         logging.debug("call setup time between %.2f and %.2f "
241                       "--------- dot transmit time: %.2f + %.2f "
242                       "receive time: between %.2f and %.2f",
243                       self.modulator.period_min,
244                       self.modulator.period_max,
245                       self.modulator.period_max,
246                       self.modulator.dot_time.dist,
247                       self.modulator.dot_time.min,
248                       self.modulator.dot_time.max)
249         logging.debug("call setup time between %.2f and %.2f "
250                       "-------- dash transmit time: %.2f + %.2f "
251                       "receive time: between %.2f and %.2f",
252                       self.modulator.period_min,
253                       self.modulator.period_max,
254                       self.modulator.period_max,
255                       self.modulator.dash_time.dist,
256                       self.modulator.dash_time.min,
257                       self.modulator.dash_time.max)
258         logging.debug("call setup time between %.2f and %.2f "
259                       "- signalspace transmit time: %.2f + %.2f "
260                       "receive time: between %.2f and %.2f",
261                       self.modulator.period_min,
262                       self.modulator.period_max,
263                       self.modulator.period_max,
264                       self.modulator.signalspace_time.dist,
265                       self.modulator.signalspace_time.min,
266                       self.modulator.signalspace_time.max)
267         logging.debug("call setup time between %.2f and %.2f "
268                       "--- wordspace transmit time: %.2f + %.2f "
269                       "receive time: between %.2f and %.2f",
270                       self.modulator.period_min,
271                       self.modulator.period_max,
272                       self.modulator.period_max,
273                       self.modulator.wordspace_time.dist,
274                       self.modulator.wordspace_time.min,
275                       self.modulator.wordspace_time.max)
276         logging.debug("call setup time between %.2f and %.2f "
277                       "--------- EOM transmit time: %.2f + %.2f "
278                       "receive time: between %.2f and inf",
279                       self.modulator.period_min,
280                       self.modulator.period_max,
281                       self.modulator.period_max,
282                       self.modulator.eom_time.dist,
283                       self.modulator.eom_time.min)
284
285         self.previous_ring_time = -1
286         self.previous_call_time = -1
287
288         self.morse_message = ""
289         self.text_message = ""
290
291         self.end_of_message = False
292
293     def receive_symbol(self):
294         current_ring_time = time.time()
295
296         if self.previous_ring_time == -1:
297             self.previous_ring_time = current_ring_time
298             self.previous_call_time = current_ring_time
299             log_symbol(0, "", "(The very first ring)")
300             return
301
302         ring_distance = current_ring_time - self.previous_ring_time
303         logging.debug("RINGs distance: %.2f", ring_distance)
304         self.previous_ring_time = current_ring_time
305
306         # Ignore multiple rings in the same call
307         if self.modulator.is_same_period(ring_distance):
308             logging.debug("multiple rings in the same call, distance: %.2f",
309                           ring_distance)
310             return
311
312         call_distance = current_ring_time - self.previous_call_time
313         self.previous_call_time = current_ring_time
314
315         try:
316             symbol = self.modulator.distance_to_symbol(call_distance)
317         except ValueError as err:
318             logging.error("%s", err)
319             logging.error("Check the transmitter and receiver parameters")
320             return
321
322         extra_info = ""
323         if symbol in [" ", "/", "EOM"]:
324             signal = self.morse_message.strip().split(' ')[-1]
325             character = self.translator.signal_to_character(signal)
326             extra_info = " got \"%s\"" % character
327
328         log_symbol(call_distance, symbol, extra_info)
329
330         if symbol != "EOM":
331             # Add spaces around the wordspace symbol to make it easier to split
332             # the Morse message in symbols later on
333             if symbol == "/":
334                 symbol = " / "
335             self.morse_message += symbol
336         else:
337             self.end_of_message = True
338             self.previous_ring_time = -1
339             self.previous_call_time = -1
340
341     def receive_loop(self):
342         while not self.end_of_message:
343             self.modem.get_response("RING")
344             self.receive_symbol()
345             logging.debug("Current message: %s", self.morse_message)
346
347         self.end_of_message = False
348         self.text_message = self.translator.morse_to_text(self.morse_message)
349         self.morse_message = ""
350
351     def get_text(self):
352         return self.text_message
353
354     def transmit_symbol(self, destination_number, symbol, sleep_time):
355         logging.info("Dial and wait %.2f = %.2f + %.2f seconds "
356                      "(transmitting '%s')",
357                      self.call_setup_time_max + sleep_time,
358                      self.call_setup_time_max,
359                      sleep_time,
360                      symbol)
361
362         # Dial, then wait self.call_setup_time_max to make sure the receiver
363         # gets at least one RING, and then hangup and sleep the time needed to
364         # transmit a symbol.
365         self.modem.send_command("ATDT" + destination_number + ";")
366         time.sleep(self.call_setup_time_max)
367         self.modem.send_command("ATH")
368         self.modem.get_response()
369         time.sleep(sleep_time)
370
371     def transmit(self, message, destination_number):
372         morse_message = self.translator.text_to_morse(message)
373         distances = self.modulator.modulate(morse_message)
374
375         logging.debug("Starting the transmission")
376         for i, distance in enumerate(distances):
377             # Use 'None' for the last call
378             if i == len(distances) - 1:
379                 symbol = None
380             else:
381                 total_sleep_time = self.call_setup_time_max + distance
382                 symbol = self.modulator.distance_to_symbol(total_sleep_time)
383
384             self.transmit_symbol(destination_number, symbol, distance)
385
386     def estimate_transmit_duration(self, message):
387         morsemessage = self.translator.text_to_morse(message)
388         logging.debug(morsemessage)
389
390         distances = self.modulator.modulate(morsemessage)
391
392         transmitting_time = 0
393         for distance in distances:
394             transmitting_time += self.call_setup_time_max
395             transmitting_time += distance
396
397         logging.debug("Estimated transmitting time: %.2f seconds",
398                       transmitting_time)
399
400
401 def test_transmit_receive():
402     logging.basicConfig(level=logging.DEBUG)
403     call_setup_time_min = 0
404     call_setup_time_max = 0.01
405     ring_time_min = 0
406     ring_time_max = 0
407
408     import random
409
410     class DummyModem(object):
411         """Always receive a '.', a '/' and then EOM, which results in 'E '."""
412
413         def __init__(self):
414             self.ring_count = 0
415
416             # Take trasmission times from a transceiver
417             self.transceiver = None
418
419             random.seed(None)
420
421         def send_command(self, command):
422             pass
423
424         def get_response(self, response=None):
425             # pylint: disable=unused-argument
426
427             setup_time = random.uniform(self.transceiver.modulator.period_min,
428                                         self.transceiver.modulator.period_max)
429
430             if self.ring_count == 0:
431                 # dummy ring
432                 pass
433             elif self.ring_count == 1:
434                 # received a '.'
435                 dot_time = self.transceiver.modulator.dot_time.dist
436                 time.sleep(setup_time + dot_time)
437             elif self.ring_count == 2:
438                 # received a '/'
439                 wordspace_time = self.transceiver.modulator.wordspace_time.dist
440                 time.sleep(setup_time + wordspace_time)
441             else:
442                 # received an 'EOM'
443                 eom_time = self.transceiver.modulator.eom_time.dist
444                 time.sleep(setup_time + eom_time)
445
446             self.ring_count += 1
447             self.ring_count %= 4
448
449     modem = DummyModem()
450
451     xcv = CallDistanceTransceiver(modem,
452                                   call_setup_time_min, call_setup_time_max,
453                                   ring_time_min, ring_time_max, True)
454
455     modem.transceiver = xcv
456
457     xcv.transmit("CODEX PARIS", "0")
458
459     while True:
460         modem.ring_count = 0
461         xcv.receive_loop()
462         print()
463         print("Message received!")
464         print("\"%s\"" % xcv.get_text(), flush=True)
465
466
467 if __name__ == "__main__":
468     test_transmit_receive()