loctrkd/beesure.py

   1 """
   2 Implementation of the protocol "beesure" used by some watch-trackers
   3 https://www.4p-touch.com/beesure-gps-setracker-server-protocol.html
   4 """
   5
   6 from datetime import datetime, timezone
   7 from enum import Enum
   8 from inspect import isclass
   9 import re
  10 from struct import error, pack, unpack
  11 from time import time
  12 from typing import (
  13     Any,
  14     Callable,
  15     Dict,
  16     List,
  17     Optional,
  18     Tuple,
  19     Type,
  20     TYPE_CHECKING,
  21     Union,
  22 )
  23 from types import SimpleNamespace
  24
  25 from .protomodule import ProtoClass
  26 from .common import (
  27     CoordReport,
  28     HintReport,
  29     StatusReport,
  30     Report,
  31 )
  32
  33 __all__ = (
  34     "Stream",
  35     "class_by_prefix",
  36     "enframe",
  37     "exposed_protos",
  38     "inline_response",
  39     "proto_handled",
  40     "parse_message",
  41     "probe_buffer",
  42     "DecodeError",
  43     "Respond",
  44 )
  45
  46 PROTO_PREFIX = "BS:"
  47
  48 ### Deframer ###
  49
  50 MAXBUFFER: int = 65557  # Theoretical max buffer 65536 + 21
  51 RE = re.compile(b"\[(\w\w)\*(\d{10})\*([0-9a-fA-F]{4})\*")
  52
  53
  54 def _framestart(buffer: bytes) -> Tuple[int, str, str, int]:
  55     """
  56     Find the start of the frame in the buffer.
  57     If found, return (offset, vendorId, imei, datalen) tuple.
  58     If not found, set -1 as the value of `offset`
  59     """
  60     mo = RE.search(buffer)
  61     return (
  62         (
  63             mo.start(),
  64             mo.group(1).decode(),
  65             mo.group(2).decode(),
  66             int(mo.group(3), 16),
  67         )
  68         if mo
  69         else (-1, "", "", 0)
  70     )
  71
  72
  73 class Stream:
  74     def __init__(self) -> None:
  75         self.buffer = b""
  76         self.imei: Optional[str] = None
  77         self.datalen: int = 0
  78
  79     def recv(self, segment: bytes) -> List[Union[bytes, str]]:
  80         """
  81         Process next segment of the stream. Return successfully deframed
  82         packets as `bytes` and error messages as `str`.
  83         """
  84         when = time()
  85         self.buffer += segment
  86         if len(self.buffer) > MAXBUFFER:
  87             # We are receiving junk. Let's drop it or we run out of memory.
  88             self.buffer = b""
  89             return [f"More than {MAXBUFFER} unparseable data, dropping"]
  90         msgs: List[Union[bytes, str]] = []
  91         while True:
  92             if not self.datalen:  # we have not seen packet start yet
  93                 toskip, _, imei, datalen = _framestart(self.buffer)
  94                 if toskip < 0:  # No frames, continue reading
  95                     break
  96                 if toskip > 0:  # Should not happen, report
  97                     msgs.append(
  98                         f"Skipping {toskip} bytes of undecodable data"
  99                         f' "{self.buffer[:toskip][:64]=!r}"'
 100                     )
 101                     self.buffer = self.buffer[toskip:]
 102                     # From this point, buffer starts with a packet header
 103                 if self.imei is None:
 104                     self.imei = imei
 105                 if self.imei != imei:
 106                     msgs.append(
 107                         f"Packet's imei {imei} mismatches"
 108                         f" previous value {self.imei}, old value kept"
 109                     )
 110                 self.datalen = datalen
 111             if len(self.buffer) < self.datalen + 21:  # Incomplete packet
 112                 break
 113             # At least one complete packet is present in the buffer
 114             if chr(self.buffer[self.datalen + 20]) == "]":
 115                 msgs.append(self.buffer[: self.datalen + 21])
 116             else:
 117                 msgs.append(
 118                     f"Packet does not end with ']'"
 119                     f" at {self.datalen+20}: {self.buffer[:64]=!r}"
 120                 )
 121             self.buffer = self.buffer[self.datalen + 21 :]
 122             self.datalen = 0
 123         return msgs
 124
 125     def close(self) -> bytes:
 126         ret = self.buffer
 127         self.buffer = b""
 128         self.imei = None
 129         self.datalen = 0
 130         return ret
 131
 132
 133 def enframe(buffer: bytes, imei: Optional[str] = None) -> bytes:
 134     assert imei is not None and len(imei) == 10
 135     off, vid, _, dlen = _framestart(buffer)
 136     assert off == 0
 137     return f"[{vid:2s}*{imei:10s}*{dlen:04X}*".encode() + buffer[20:]
 138
 139
 140 ### Parser/Constructor ###
 141
 142
 143 class classproperty:
 144     def __init__(self, f: Callable[[Any], str]) -> None:
 145         self.f = f
 146
 147     def __get__(self, obj: Any, owner: Any) -> str:
 148         return self.f(owner)
 149
 150
 151 class DecodeError(Exception):
 152     def __init__(self, e: Exception, **kwargs: Any) -> None:
 153         super().__init__(e)
 154         for k, v in kwargs.items():
 155             setattr(self, k, v)
 156
 157
 158 def maybe(typ: type) -> Callable[[Any], Any]:
 159     return lambda x: None if x is None else typ(x)
 160
 161
 162 def intx(x: Union[str, int]) -> int:
 163     if isinstance(x, str):
 164         x = int(x, 0)
 165     return x
 166
 167
 168 def boolx(x: Union[str, bool]) -> bool:
 169     if isinstance(x, str):
 170         if x.upper() in ("ON", "TRUE", "1"):
 171             return True
 172         if x.upper() in ("OFF", "FALSE", "0"):
 173             return False
 174         raise ValueError(str(x) + " could not be parsed as a Boolean")
 175     return x
 176
 177
 178 def l3str(x: Union[str, List[str]]) -> List[str]:
 179     if isinstance(x, str):
 180         lx = x.split(",")
 181     else:
 182         lx = x
 183     if len(lx) != 3 or not all(isinstance(el, str) for el in x):
 184         raise ValueError(str(lx) + " is not a list of three strings")
 185     return lx
 186
 187
 188 def pblist(x: Union[str, List[Tuple[str, str]]]) -> List[Tuple[str, str]]:
 189     if isinstance(x, str):
 190
 191         def splitpair(s: str) -> Tuple[str, str]:
 192             a, b = s.split(":")
 193             return a, b
 194
 195         lx = [splitpair(el) for el in x.split(",")]
 196     else:
 197         lx = x
 198     if len(lx) > 5:
 199         raise ValueError(str(lx) + " has too many elements (max 5)")
 200     return lx
 201
 202
 203 class Respond(Enum):
 204     NON = 0  # Incoming, no response needed
 205     INL = 1  # Birirectional, use `inline_response()`
 206     EXT = 2  # Birirectional, use external responder
 207
 208
 209 class BeeSurePkt(ProtoClass):
 210     BINARY = False
 211     RESPOND = Respond.NON  # Do not send anything back by default
 212     IN_KWARGS: Tuple[Tuple[str, Callable[[Any], Any], Any], ...] = ()
 213     OUT_KWARGS: Tuple[Tuple[str, Callable[[Any], Any], Any], ...] = ()
 214     KWARGS: Tuple[Tuple[str, Callable[[Any], Any], Any], ...] = ()
 215     In: Type["BeeSurePkt"]
 216     Out: Type["BeeSurePkt"]
 217
 218     if TYPE_CHECKING:
 219
 220         def __getattr__(self, name: str) -> Any:
 221             pass
 222
 223         def __setattr__(self, name: str, value: Any) -> None:
 224             pass
 225
 226     def __init__(self, *args: Any, **kwargs: Any):
 227         """
 228         Construct the object _either_ from (length, payload),
 229         _or_ from the values of individual fields
 230         """
 231         self.payload: Union[List[str], bytes]
 232         assert not args or (len(args) == 4 and not kwargs)
 233         if args:  # guaranteed to be two arguments at this point
 234             self.vendor, self.imei, self.datalength, self.payload = args
 235             try:
 236                 if isinstance(self.payload, list):
 237                     self.decode(*self.payload)
 238                 else:
 239                     self.decode(self.payload)
 240             except error as e:
 241                 raise DecodeError(e, obj=self)
 242         else:
 243             for kw, typ, dfl in self.KWARGS:
 244                 setattr(self, kw, typ(kwargs.pop(kw, dfl)))
 245             if kwargs:
 246                 raise ValueError(
 247                     self.__class__.__name__ + " stray kwargs " + str(kwargs)
 248                 )
 249
 250     def __repr__(self) -> str:
 251         return "{}({})".format(
 252             self.__class__.__name__,
 253             ", ".join(
 254                 "{}={}".format(
 255                     k,
 256                     'bytes.fromhex("{}")'.format(v.hex())
 257                     if isinstance(v, bytes)
 258                     else v.__repr__(),
 259                 )
 260                 for k, v in self.__dict__.items()
 261                 if not k.startswith("_")
 262             ),
 263         )
 264
 265     def decode(self, *args: Any) -> None:
 266         ...
 267
 268     def in_decode(self, *args: str) -> None:
 269         # Overridden in subclasses, otherwise do not decode payload
 270         return
 271
 272     def out_decode(self, *args: str) -> None:
 273         # Overridden in subclasses, otherwise do not decode payload
 274         return
 275
 276     def encode(self) -> str:
 277         ...
 278
 279     def in_encode(self) -> str:
 280         # Necessary to emulate terminal, which is not implemented
 281         raise NotImplementedError(
 282             self.__class__.__name__ + ".encode() not implemented"
 283         )
 284
 285     def out_encode(self) -> str:
 286         # Overridden in subclasses, otherwise command verb only
 287         return ""
 288
 289     @classproperty
 290     def PROTO(cls: "BeeSurePkt") -> str:
 291         """Name of the class without possible .In / .Out suffix"""
 292         proto: str
 293         try:
 294             proto, _ = cls.__name__.split(".")
 295         except ValueError:
 296             proto = cls.__name__
 297         return proto
 298
 299     @classmethod
 300     def proto_name(cls) -> str:
 301         """Name of the command as used externally"""
 302         return PROTO_PREFIX + cls.PROTO[:16]
 303
 304     @property
 305     def packed(self) -> bytes:
 306         data = self.encode()
 307         payload = self.PROTO + "," + data if data else self.PROTO
 308         return f"[LT*0000000000*{len(payload):04X}*{payload}]".encode()
 309
 310
 311 class UNKNOWN(BeeSurePkt):
 312     pass
 313
 314
 315 class _SET_PHONE(BeeSurePkt):
 316     OUT_KWARGS = (("phonenumber", str, ""),)
 317
 318     def out_encode(self) -> str:
 319         self.phonenumber: str
 320         return self.phonenumber
 321
 322
 323 class _LOC_DATA(BeeSurePkt):
 324     def in_decode(self, *args: str) -> None:
 325         p = SimpleNamespace()
 326         _id = lambda x: x
 327         for (obj, attr, func), val in zip(
 328             (
 329                 (p, "date", _id),
 330                 (p, "time", _id),
 331                 (self, "gps_valid", lambda x: x == "A"),
 332                 (p, "lat", float),
 333                 (p, "nors", lambda x: 1 if x == "N" else -1),
 334                 (p, "lon", float),
 335                 (p, "eorw", lambda x: 1 if x == "E" else -1),
 336                 (self, "speed", float),
 337                 (self, "direction", float),
 338                 (self, "altitude", float),
 339                 (self, "num_of_sats", int),
 340                 (self, "gsm_strength_percentage", int),
 341                 (self, "battery_percentage", int),
 342                 (self, "pedometer", int),
 343                 (self, "tubmling_times", int),
 344                 (self, "device_status", lambda x: int(x, 16)),
 345                 (self, "gsm_cells_number", int),
 346                 (self, "connect_base_station_number", int),
 347                 (self, "mcc", int),
 348                 (self, "mnc", int),
 349             ),
 350             args[:20],
 351         ):
 352             setattr(obj, attr, func(val))  # type: ignore
 353         rest_args = args[20:]
 354         # (area_id, cell_id, strength)*
 355         self.gsm_cells: List[Tuple[int, int, int]] = [
 356             tuple(int(el) for el in rest_args[i * 3 : 3 + i * 3])  # type: ignore
 357             for i in range(self.gsm_cells_number)
 358         ]
 359         rest_args = rest_args[3 * self.gsm_cells_number :]
 360         self.wifi_aps_number = int(rest_args[0])
 361         # (SSID, MAC, strength)*
 362         self.wifi_aps = [
 363             (
 364                 rest_args[1 + i * 3],
 365                 rest_args[2 + i * 3],
 366                 int(rest_args[3 + i * 3]),
 367             )
 368             for i in range(self.wifi_aps_number)
 369         ]
 370         rest_args = rest_args[1 + 3 * self.wifi_aps_number :]
 371         self.positioning_accuracy = float(rest_args[0])
 372         self.devtime = (
 373             datetime.strptime(
 374                 p.date + p.time,
 375                 "%d%m%y%H%M%S",
 376             )
 377             # .replace(tzinfo=timezone.utc)
 378             # .astimezone(tz=timezone.utc)
 379         )
 380         self.latitude = p.lat * p.nors
 381         self.longitude = p.lon * p.eorw
 382
 383     def rectified(self) -> Report:
 384         # self.gps_valid is supposed to mean it, but it does not. Perfectly
 385         # good looking coordinates, with ten satellites, still get 'V'.
 386         # I suspect that in reality, 'A' means "hint data is absent".
 387         if self.gps_valid or self.num_of_sats > 3:
 388             return CoordReport(
 389                 devtime=str(self.devtime),
 390                 battery_percentage=self.battery_percentage,
 391                 accuracy=self.positioning_accuracy,
 392                 altitude=self.altitude,
 393                 speed=self.speed,
 394                 direction=self.direction,
 395                 latitude=self.latitude,
 396                 longitude=self.longitude,
 397             )
 398         else:
 399             return HintReport(
 400                 devtime=str(self.devtime),
 401                 battery_percentage=self.battery_percentage,
 402                 mcc=self.mcc,
 403                 mnc=self.mnc,
 404                 gsm_cells=self.gsm_cells,
 405                 wifi_aps=self.wifi_aps,
 406             )
 407
 408
 409 class AL(_LOC_DATA):
 410     RESPOND = Respond.INL
 411
 412
 413 class CALL(_SET_PHONE):
 414     pass
 415
 416
 417 class CENTER(_SET_PHONE):
 418     pass
 419
 420
 421 class CONFIG(BeeSurePkt):
 422     pass
 423
 424
 425 class CR(BeeSurePkt):
 426     pass
 427
 428
 429 class FIND(BeeSurePkt):
 430     pass
 431
 432
 433 class FLOWER(BeeSurePkt):
 434     OUT_KWARGS = (("number", int, 1),)
 435
 436     def out_encode(self) -> str:
 437         self.number: int
 438         return str(self.number)
 439
 440
 441 class ICCID(BeeSurePkt):
 442     pass
 443
 444
 445 class LK(BeeSurePkt):
 446     RESPOND = Respond.INL
 447
 448     def in_decode(self, *args: str) -> None:
 449         numargs = len(args)
 450         if numargs > 0:
 451             self.step = args[0]
 452         if numargs > 1:
 453             self.tumbling_number = args[1]
 454         if numargs > 2:
 455             self.battery_percentage = args[2]
 456
 457     def in_encode(self) -> str:
 458         return "LK"
 459
 460
 461 class LZ(BeeSurePkt):
 462     OUT_KWARGS = (("language", int, 1), ("timezone", int, 0))
 463
 464     def out_encode(self) -> str:
 465         return f"{self.language},{self.timezone}"
 466
 467
 468 class MESSAGE(BeeSurePkt):
 469     OUT_KWARGS = (("message", str, ""),)
 470
 471     def out_encode(self) -> str:
 472         return str(self.message.encode("utf_16_be").hex())
 473
 474
 475 class MONITOR(BeeSurePkt):
 476     pass
 477
 478
 479 class _PHB(BeeSurePkt):
 480     OUT_KWARGS: Tuple[Tuple[str, Callable[[Any], Any], Any], ...] = (
 481         ("entries", pblist, []),
 482     )
 483
 484     def out_encode(self) -> str:
 485         self.entries: List[Tuple[str, str]]
 486         return ",".join(
 487             [
 488                 ",".join((num, name.encode("utf_16_be").hex()))
 489                 for name, num in self.entries
 490             ]
 491         )
 492
 493
 494 class PHB(_PHB):
 495     pass
 496
 497
 498 class PHB2(_PHB):
 499     pass
 500
 501
 502 class POWEROFF(BeeSurePkt):
 503     pass
 504
 505
 506 class RESET(BeeSurePkt):
 507     pass
 508
 509
 510 class SOS(BeeSurePkt):
 511     OUT_KWARGS = (("phonenumbers", l3str, ["", "", ""]),)
 512
 513     def out_encode(self) -> str:
 514         self.phonenumbers: List[str]
 515         return ",".join(self.phonenumbers)
 516
 517
 518 class SOS1(_SET_PHONE):
 519     pass
 520
 521
 522 class SOS2(_SET_PHONE):
 523     pass
 524
 525
 526 class SOS3(_SET_PHONE):
 527     pass
 528
 529
 530 class TK(BeeSurePkt):
 531     BINARY = True
 532     RESPOND = Respond.INL
 533
 534     def in_decode(self, *args: Any) -> None:
 535         assert len(args) == 1 and isinstance(args[0], bytes)
 536         self.amr_data = (
 537             args[0]
 538             .replace(b"}*", b"*")
 539             .replace(b"},", b",")
 540             .replace(b"}[", b"[")
 541             .replace(b"}]", b"]")
 542             .replace(b"}}", b"}")
 543         )
 544
 545     def out_encode(self) -> str:
 546         return "1"  # 0 - receive failure, 1 - receive success
 547
 548
 549 class TKQ(BeeSurePkt):
 550     RESPOND = Respond.INL
 551
 552
 553 class TKQ2(BeeSurePkt):
 554     RESPOND = Respond.INL
 555
 556
 557 class UD(_LOC_DATA):
 558     pass
 559
 560
 561 class UD2(_LOC_DATA):
 562     pass
 563
 564
 565 class UPLOAD(BeeSurePkt):
 566     OUT_KWARGS = (("interval", int, 600),)
 567
 568     def out_encode(self) -> str:
 569         return str(self.interval)
 570
 571
 572 # Build dicts protocol number -> class and class name -> protocol number
 573 CLASSES = {}
 574 if True:  # just to indent the code, sorry!
 575     for cls in [
 576         cls
 577         for name, cls in globals().items()
 578         if isclass(cls)
 579         and issubclass(cls, BeeSurePkt)
 580         and not name.startswith("_")
 581     ]:
 582         CLASSES[cls.__name__] = cls
 583
 584
 585 def class_by_prefix(
 586     prefix: str,
 587 ) -> Union[Type[BeeSurePkt], List[str]]:
 588     if prefix.startswith(PROTO_PREFIX):
 589         pname = prefix[len(PROTO_PREFIX) :].upper()
 590     else:
 591         raise KeyError(pname)
 592     lst = [name for name in CLASSES.keys() if name.upper().startswith(pname)]
 593     for proto in lst:
 594         if len(lst) == 1:  # unique prefix match
 595             return CLASSES[proto]
 596         if proto == pname:  # exact match
 597             return CLASSES[proto]
 598     return lst
 599
 600
 601 def proto_handled(proto: str) -> bool:
 602     return proto.startswith(PROTO_PREFIX)
 603
 604
 605 def _local_proto(packet: bytes) -> str:
 606     try:
 607         return packet[20:-1].split(b",")[0].decode()
 608     except UnicodeDecodeError:
 609         return "UNKNOWN"
 610
 611
 612 def proto_of_message(packet: bytes) -> str:
 613     return PROTO_PREFIX + _local_proto(packet)
 614
 615
 616 def imei_from_packet(packet: bytes) -> Optional[str]:
 617     toskip, _, imei, _ = _framestart(packet)
 618     if toskip == 0 and imei != "":
 619         return imei
 620     return None
 621
 622
 623 def is_goodbye_packet(packet: bytes) -> bool:
 624     return False
 625
 626
 627 def inline_response(packet: bytes) -> Optional[bytes]:
 628     proto = _local_proto(packet)
 629     if proto in CLASSES:
 630         cls = CLASSES[proto]
 631         if cls.RESPOND is Respond.INL:
 632             return cls.Out().packed
 633     return None
 634
 635
 636 def probe_buffer(buffer: bytes) -> bool:
 637     return bool(RE.search(buffer))
 638
 639
 640 def parse_message(packet: bytes, is_incoming: bool = True) -> BeeSurePkt:
 641     """From a packet (without framing bytes) derive the XXX.In object"""
 642     toskip, vendor, imei, datalength = _framestart(packet)
 643     bsplits = packet[20:-1].split(b",", 1)
 644     try:
 645         proto = bsplits[0].decode("ascii")
 646     except UnicodeDecodeError:
 647         proto = str(bsplits[0])
 648     if len(bsplits) == 2:
 649         rest = bsplits[1]
 650     else:
 651         rest = b""
 652     if proto in CLASSES:
 653         cls = CLASSES[proto].In if is_incoming else CLASSES[proto].Out
 654         payload = (
 655             # Some people encode their SSIDs in non-utf8
 656             rest
 657             if cls.BINARY
 658             else rest.decode("Windows-1252").split(",")
 659         )
 660         try:
 661             return cls(vendor, imei, datalength, payload)
 662         except (DecodeError, ValueError, IndexError) as e:
 663             cause: Union[DecodeError, ValueError, IndexError] = e
 664     else:
 665         payload = rest
 666         cause = ValueError(f"Proto {proto} is unknown")
 667     if is_incoming:
 668         retobj = UNKNOWN.In(vendor, imei, datalength, payload)
 669     else:
 670         retobj = UNKNOWN.Out(vendor, imei, datalength, payload)
 671     retobj.proto = proto  # Override class attr with object attr
 672     retobj.cause = cause
 673     return retobj
 674
 675
 676 def exposed_protos() -> List[Tuple[str, bool]]:
 677     return [
 678         (cls.proto_name(), False)
 679         for cls in CLASSES.values()
 680         if hasattr(cls, "rectified")
 681     ]