588c9852abc8469159b69a996f1ac5c2280fa2dc
[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 class CallDistanceTransceiver(object):
165     """Transmit Morse messages using the distance between calls.
166
167     This is basically a pulse-distance modulation (PDM).
168
169     A RING is a pulse and the Morse symbols are encoded in the pause between
170     the first ring of the previous call and the first ring of a new call.
171
172     This strategy is very slow but it can even be used with ancient analog
173     modems which don't have call progress notifications for outgoing calls, and
174     make it also hard to count multiple rings in the same call on the receiving
175     side because there is no explicit notification on the receiving side of
176     when the caller ends a calls.
177
178     For GSM modems, which have a more sophisticate call report signalling,
179     a more efficient encoding can be used (for example using ring counts to
180     encode Morse symbols, i.e. a pulse-length modulation), but for
181     a proof-of-concept, a slow encoding covering the most general setup is
182     fine.
183
184     Plus, supporting communications between analog modems is cool :)
185     """
186
187     def __init__(self, modem,
188                  call_setup_time_min=7, call_setup_time_max=15,
189                  ring_time_min=4.8, ring_time_max=5.2,
190                  add_inter_call_distance=True):
191         """Encode the Morse symbols using the distance between calls.
192
193         Args:
194
195             call_setup_time_min: the minimum time between  when the transmitter
196                 dials the number and the receiver reports RING notifications.
197             call_setup_time_max: the maximum time between when the transmitter
198                 dials the number and the receiver reports RING notifications.
199                 Waiting this time after dialing ensures that the receiver has
200                 received _at_least_ one ring. The default chosen here have been
201                 tested to work fine with old analog modems, provided that there
202                 is some more distance between two calls, and with Android
203                 receivers.
204             ring_time_min: the minimum time between two consecutive RINGs
205                 in the same call.
206             ring_time_max: the maximum time between two consecutive RINGs
207                 in the same call, the standard interval is about 5 seconds, but
208                 line and/or software delays can make it vary.  This is needed
209                 in order to ignore multiple ring in the same call when multiple
210                 RING in the same call are notified, and then be able to
211                 discriminate between two different calls.
212             add_inter_call_distance: specify if it is needed to wait an extra
213                 fixed time between calls.
214             """
215
216         self.modem = modem
217         self.translator = MorseTranslator()
218
219         self.destination_number = ""
220
221         self.call_setup_time_max = call_setup_time_max
222
223         if add_inter_call_distance:
224             # Analog modems don't like to dial a new call immediately after
225             # they hung up the previous one; an extra delay of about one
226             # ring time makes them happy.
227             inter_symbol_distance = ring_time_max
228         else:
229             inter_symbol_distance = 0
230
231         self.modulator = MorseDistanceModulator(call_setup_time_min,
232                                                 call_setup_time_max,
233                                                 ring_time_min,
234                                                 ring_time_max,
235                                                 inter_symbol_distance)
236
237         logging.debug("call setup time between %.2f and %.2f "
238                       "--------- dot transmit time: %.2f + %.2f "
239                       "receive time: between %.2f and %.2f",
240                       self.modulator.period_min,
241                       self.modulator.period_max,
242                       self.modulator.period_max,
243                       self.modulator.dot_time.dist,
244                       self.modulator.dot_time.min,
245                       self.modulator.dot_time.max)
246         logging.debug("call setup time between %.2f and %.2f "
247                       "-------- dash transmit time: %.2f + %.2f "
248                       "receive time: between %.2f and %.2f",
249                       self.modulator.period_min,
250                       self.modulator.period_max,
251                       self.modulator.period_max,
252                       self.modulator.dash_time.dist,
253                       self.modulator.dash_time.min,
254                       self.modulator.dash_time.max)
255         logging.debug("call setup time between %.2f and %.2f "
256                       "- signalspace transmit time: %.2f + %.2f "
257                       "receive time: between %.2f and %.2f",
258                       self.modulator.period_min,
259                       self.modulator.period_max,
260                       self.modulator.period_max,
261                       self.modulator.signalspace_time.dist,
262                       self.modulator.signalspace_time.min,
263                       self.modulator.signalspace_time.max)
264         logging.debug("call setup time between %.2f and %.2f "
265                       "--- wordspace transmit time: %.2f + %.2f "
266                       "receive time: between %.2f and %.2f",
267                       self.modulator.period_min,
268                       self.modulator.period_max,
269                       self.modulator.period_max,
270                       self.modulator.wordspace_time.dist,
271                       self.modulator.wordspace_time.min,
272                       self.modulator.wordspace_time.max)
273         logging.debug("call setup time between %.2f and %.2f "
274                       "--------- EOM transmit time: %.2f + %.2f "
275                       "receive time: between %.2f and inf",
276                       self.modulator.period_min,
277                       self.modulator.period_max,
278                       self.modulator.period_max,
279                       self.modulator.eom_time.dist,
280                       self.modulator.eom_time.min)
281
282         self.previous_ring_time = -1
283         self.previous_call_time = -1
284
285         self.morse_message = ""
286         self.text_message = ""
287
288         self.end_of_message = False
289
290     def log_symbol(self, distance, symbol, extra_info=""):
291         logging.info("distance: %.2f Received \"%s\"%s", distance, symbol,
292                      extra_info)
293
294     def receive_character(self):
295         current_ring_time = time.time()
296
297         if self.previous_ring_time == -1:
298             self.previous_ring_time = current_ring_time
299             self.previous_call_time = current_ring_time
300             self.log_symbol(0, "", "(The very first ring)")
301             return
302
303         ring_distance = current_ring_time - self.previous_ring_time
304         logging.debug("RINGs distance: %.2f", ring_distance)
305         self.previous_ring_time = current_ring_time
306
307         # Ignore multiple rings in the same call
308         if self.modulator.is_same_period(ring_distance):
309             logging.debug("multiple rings in the same call, distance: %.2f",
310                           ring_distance)
311             return
312
313         call_distance = current_ring_time - self.previous_call_time
314         self.previous_call_time = current_ring_time
315
316         try:
317             symbol = self.modulator.distance_to_symbol(call_distance)
318         except ValueError as err:
319             logging.error("%s", err)
320             logging.error("Check the transmitter and receiver parameters")
321             return
322
323         extra_info = ""
324         if symbol in [" ", "/", "EOM"]:
325             signal = self.morse_message.strip().split(' ')[-1]
326             character = self.translator.signal_to_character(signal)
327             extra_info = " got \"%s\"" % character
328
329         self.log_symbol(call_distance, symbol, extra_info)
330
331         if symbol != "EOM":
332             # Add spaces around the wordspace symbol to make it easier to split
333             # the Morse message in symbols later on
334             if symbol == "/":
335                 symbol = " / "
336             self.morse_message += symbol
337         else:
338             self.end_of_message = True
339             self.previous_ring_time = -1
340             self.previous_call_time = -1
341
342     def receive_loop(self):
343         while not self.end_of_message:
344             self.modem.get_response("RING")
345             self.receive_character()
346             logging.debug("Current message: %s", self.morse_message)
347
348         self.end_of_message = False
349         self.text_message = self.translator.morse_to_text(self.morse_message)
350         self.morse_message = ""
351
352     def get_text(self):
353         return self.text_message
354
355     def transmit_symbol(self, symbol, sleep_time):
356         logging.info("Dial and wait %.2f = %.2f + %.2f seconds "
357                      "(transmitting '%s')",
358                      self.call_setup_time_max + sleep_time,
359                      self.call_setup_time_max,
360                      sleep_time,
361                      symbol)
362
363         # Dial, then wait self.call_setup_time_max to make sure the receiver
364         # gets at least one RING, and then hangup and sleep the time needed to
365         # transmit a symbol.
366         self.modem.send_command("ATDT" + self.destination_number + ";")
367         time.sleep(self.call_setup_time_max)
368         self.modem.send_command("ATH")
369         self.modem.get_response()
370         time.sleep(sleep_time)
371
372     def transmit(self, message, destination_number):
373         self.destination_number = destination_number
374
375         morse_message = self.translator.text_to_morse(message)
376         distances = self.modulator.modulate(morse_message)
377
378         logging.debug("Starting the transmission")
379         for i, distance in enumerate(distances):
380             # Use 'None' for the last call
381             if i == len(distances) - 1:
382                 symbol = None
383             else:
384                 total_sleep_time = self.call_setup_time_max + distance
385                 symbol = self.modulator.distance_to_symbol(total_sleep_time)
386
387             self.transmit_symbol(symbol, distance)
388
389     def estimate_transmit_duration(self, message):
390         morsemessage = self.translator.text_to_morse(message)
391         logging.debug(morsemessage)
392
393         distances = self.modulator.modulate(morsemessage)
394
395         transmitting_time = 0
396         for distance in distances:
397             transmitting_time += self.call_setup_time_max
398             transmitting_time += distance
399
400         logging.debug("Estimated transmitting time: %.2f seconds",
401                       transmitting_time)
402
403
404 def test_send_receive():
405     logging.basicConfig(level=logging.DEBUG)
406     call_setup_time_min = 0
407     call_setup_time_max = 0.01
408     ring_time_min = 0
409     ring_time_max = 0
410
411     import random
412
413     class DummyModem(object):
414         """Always receive a '.', a '/' and then EOM, which results in 'E '."""
415
416         def __init__(self):
417             self.ring_count = 0
418
419             # Take trasmission times from a transceiver
420             self.transceiver = None
421
422             random.seed(None)
423
424         def send_command(self, command):
425             pass
426
427         def get_response(self, response):
428             # pylint: disable=unused-argument
429
430             setup_time = random.uniform(self.transceiver.modulator.period_min,
431                                         self.transceiver.modulator.period_max)
432
433             if self.ring_count == 0:
434                 # dummy ring
435                 pass
436             elif self.ring_count == 1:
437                 # received a '.'
438                 dot_time = self.transceiver.modulator.dot_time.dist
439                 time.sleep(setup_time + dot_time)
440             elif self.ring_count == 2:
441                 # received a '/'
442                 wordspace_time = self.transceiver.modulator.wordspace_time.dist
443                 time.sleep(setup_time + wordspace_time)
444             else:
445                 # received an 'EOM'
446                 eom_time = self.transceiver.modulator.eom_time.dist
447                 time.sleep(setup_time + eom_time)
448
449             self.ring_count += 1
450             self.ring_count %= 4
451
452     modem = DummyModem()
453
454     xcv = CallDistanceTransceiver(modem,
455                                   call_setup_time_min, call_setup_time_max,
456                                   ring_time_min, ring_time_max, True)
457
458     modem.transceiver = xcv
459
460     while True:
461         xcv.receive_loop()
462         modem.ring_count = 0
463         print()
464         print("Message received!")
465         print("\"%s\"" % xcv.get_text(), flush=True)
466
467
468 if __name__ == "__main__":
469     test_send_receive()