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 __all__ = (
  26     "Stream",
  27     "class_by_prefix",
  28     "enframe",
  29     "inline_response",
  30     "proto_handled",
  31     "parse_message",
  32     "probe_buffer",
  33     "proto_name",
  34     "DecodeError",
  35     "Respond",
  36     "LK",
  37 )
  38
  39 PROTO_PREFIX = "BS:"
  40
  41 ### Deframer ###
  42
  43 MAXBUFFER: int = 65557  # Theoretical max buffer 65536 + 21
  44 RE = re.compile(b"\[(\w\w)\*(\d{10})\*([0-9a-fA-F]{4})\*")
  45
  46
  47 def _framestart(buffer: bytes) -> Tuple[int, str, str, int]:
  48     """
  49     Find the start of the frame in the buffer.
  50     If found, return (offset, vendorId, imei, datalen) tuple.
  51     If not found, set -1 as the value of `offset`
  52     """
  53     mo = RE.search(buffer)
  54     return (
  55         (
  56             mo.start(),
  57             mo.group(1).decode(),
  58             mo.group(2).decode(),
  59             int(mo.group(3), 16),
  60         )
  61         if mo
  62         else (-1, "", "", 0)
  63     )
  64
  65
  66 class Stream:
  67     def __init__(self) -> None:
  68         self.buffer = b""
  69         self.imei: Optional[str] = None
  70         self.datalen: int = 0
  71
  72     def recv(self, segment: bytes) -> List[Union[bytes, str]]:
  73         """
  74         Process next segment of the stream. Return successfully deframed
  75         packets as `bytes` and error messages as `str`.
  76         """
  77         when = time()
  78         self.buffer += segment
  79         if len(self.buffer) > MAXBUFFER:
  80             # We are receiving junk. Let's drop it or we run out of memory.
  81             self.buffer = b""
  82             return [f"More than {MAXBUFFER} unparseable data, dropping"]
  83         msgs: List[Union[bytes, str]] = []
  84         while True:
  85             if not self.datalen:  # we have not seen packet start yet
  86                 toskip, _, imei, datalen = _framestart(self.buffer)
  87                 if toskip < 0:  # No frames, continue reading
  88                     break
  89                 if toskip > 0:  # Should not happen, report
  90                     msgs.append(
  91                         f"Skipping {toskip} bytes of undecodable data"
  92                         f' "{self.buffer[:toskip][:64]=!r}"'
  93                     )
  94                     self.buffer = self.buffer[toskip:]
  95                     # From this point, buffer starts with a packet header
  96                 if self.imei is None:
  97                     self.imei = imei
  98                 if self.imei != imei:
  99                     msgs.append(
 100                         f"Packet's imei {imei} mismatches"
 101                         f" previous value {self.imei}, old value kept"
 102                     )
 103                 self.datalen = datalen
 104             if len(self.buffer) < self.datalen + 21:  # Incomplete packet
 105                 break
 106             # At least one complete packet is present in the buffer
 107             if chr(self.buffer[self.datalen + 20]) == "]":
 108                 msgs.append(self.buffer[: self.datalen + 21])
 109             else:
 110                 msgs.append(
 111                     f"Packet does not end with ']'"
 112                     f" at {self.datalen+20}: {self.buffer=!r}"
 113                 )
 114             self.buffer = self.buffer[self.datalen + 21 :]
 115             self.datalen = 0
 116         return msgs
 117
 118     def close(self) -> bytes:
 119         ret = self.buffer
 120         self.buffer = b""
 121         self.imei = None
 122         self.datalen = 0
 123         return ret
 124
 125
 126 def enframe(buffer: bytes, imei: Optional[str] = None) -> bytes:
 127     assert imei is not None and len(imei) == 10
 128     off, vid, _, dlen = _framestart(buffer)
 129     assert off == 0
 130     return f"[{vid:2s}*{imei:10s}*{dlen:04X}*".encode() + buffer[20:]
 131
 132
 133 ### Parser/Constructor ###
 134
 135
 136 class DecodeError(Exception):
 137     def __init__(self, e: Exception, **kwargs: Any) -> None:
 138         super().__init__(e)
 139         for k, v in kwargs.items():
 140             setattr(self, k, v)
 141
 142
 143 def maybe(typ: type) -> Callable[[Any], Any]:
 144     return lambda x: None if x is None else typ(x)
 145
 146
 147 def intx(x: Union[str, int]) -> int:
 148     if isinstance(x, str):
 149         x = int(x, 0)
 150     return x
 151
 152
 153 def boolx(x: Union[str, bool]) -> bool:
 154     if isinstance(x, str):
 155         if x.upper() in ("ON", "TRUE", "1"):
 156             return True
 157         if x.upper() in ("OFF", "FALSE", "0"):
 158             return False
 159         raise ValueError(str(x) + " could not be parsed as a Boolean")
 160     return x
 161
 162
 163 def l3str(x: Union[str, List[str]]) -> List[str]:
 164     if isinstance(x, str):
 165         lx = x.split(",")
 166     else:
 167         lx = x
 168     if len(lx) != 3 or not all(isinstance(el, str) for el in x):
 169         raise ValueError(str(lx) + " is not a list of three strings")
 170     return lx
 171
 172
 173 class MetaPkt(type):
 174     """
 175     For each class corresponding to a message, automatically create
 176     two nested classes `In` and `Out` that also inherit from their
 177     "nest". Class attribute `IN_KWARGS` defined in the "nest" is
 178     copied to the `In` nested class under the name `KWARGS`, and
 179     likewise, `OUT_KWARGS` of the nest class is copied as `KWARGS`
 180     to the nested class `Out`. In addition, method `encode` is
 181     defined in both classes equal to `in_encode()` and `out_encode()`
 182     respectively.
 183     """
 184
 185     if TYPE_CHECKING:
 186
 187         def __getattr__(self, name: str) -> Any:
 188             pass
 189
 190         def __setattr__(self, name: str, value: Any) -> None:
 191             pass
 192
 193     def __new__(
 194         cls: Type["MetaPkt"],
 195         name: str,
 196         bases: Tuple[type, ...],
 197         attrs: Dict[str, Any],
 198     ) -> "MetaPkt":
 199         newcls = super().__new__(cls, name, bases, attrs)
 200         newcls.In = super().__new__(
 201             cls,
 202             name + ".In",
 203             (newcls,) + bases,
 204             {
 205                 "KWARGS": newcls.IN_KWARGS,
 206                 "decode": newcls.in_decode,
 207                 "encode": newcls.in_encode,
 208             },
 209         )
 210         newcls.Out = super().__new__(
 211             cls,
 212             name + ".Out",
 213             (newcls,) + bases,
 214             {
 215                 "KWARGS": newcls.OUT_KWARGS,
 216                 "decode": newcls.out_decode,
 217                 "encode": newcls.out_encode,
 218             },
 219         )
 220         return newcls
 221
 222
 223 class Respond(Enum):
 224     NON = 0  # Incoming, no response needed
 225     INL = 1  # Birirectional, use `inline_response()`
 226     EXT = 2  # Birirectional, use external responder
 227
 228
 229 class BeeSurePkt(metaclass=MetaPkt):
 230     RESPOND = Respond.NON  # Do not send anything back by default
 231     IN_KWARGS: Tuple[Tuple[str, Callable[[Any], Any], Any], ...] = ()
 232     OUT_KWARGS: Tuple[Tuple[str, Callable[[Any], Any], Any], ...] = ()
 233     KWARGS: Tuple[Tuple[str, Callable[[Any], Any], Any], ...] = ()
 234     In: Type["BeeSurePkt"]
 235     Out: Type["BeeSurePkt"]
 236
 237     if TYPE_CHECKING:
 238
 239         def __getattr__(self, name: str) -> Any:
 240             pass
 241
 242         def __setattr__(self, name: str, value: Any) -> None:
 243             pass
 244
 245     def __init__(self, *args: Any, **kwargs: Any):
 246         """
 247         Construct the object _either_ from (length, payload),
 248         _or_ from the values of individual fields
 249         """
 250         assert not args or (len(args) == 4 and not kwargs)
 251         if args:  # guaranteed to be two arguments at this point
 252             self.vendor, self.imei, self.datalength, self.payload = args
 253             try:
 254                 self.decode(*self.payload)
 255             except error as e:
 256                 raise DecodeError(e, obj=self)
 257         else:
 258             for kw, typ, dfl in self.KWARGS:
 259                 setattr(self, kw, typ(kwargs.pop(kw, dfl)))
 260             if kwargs:
 261                 raise ValueError(
 262                     self.__class__.__name__ + " stray kwargs " + str(kwargs)
 263                 )
 264
 265     def __repr__(self) -> str:
 266         return "{}({})".format(
 267             self.__class__.__name__,
 268             ", ".join(
 269                 "{}={}".format(
 270                     k,
 271                     'bytes.fromhex("{}")'.format(v.hex())
 272                     if isinstance(v, bytes)
 273                     else v.__repr__(),
 274                 )
 275                 for k, v in self.__dict__.items()
 276                 if not k.startswith("_")
 277             ),
 278         )
 279
 280     def decode(self, *args: str) -> None:
 281         ...
 282
 283     def in_decode(self, *args: str) -> None:
 284         # Overridden in subclasses, otherwise do not decode payload
 285         return
 286
 287     def out_decode(self, *args: str) -> None:
 288         # Overridden in subclasses, otherwise do not decode payload
 289         return
 290
 291     def encode(self) -> str:
 292         ...
 293
 294     def in_encode(self) -> str:
 295         # Necessary to emulate terminal, which is not implemented
 296         raise NotImplementedError(
 297             self.__class__.__name__ + ".encode() not implemented"
 298         )
 299
 300     def out_encode(self) -> str:
 301         # Overridden in subclasses, otherwise command verb only
 302         return ""
 303
 304     @property
 305     def PROTO(self) -> str:
 306         try:
 307             proto, _ = self.__class__.__name__.split(".")
 308         except ValueError:
 309             proto = self.__class__.__name__
 310         return proto
 311
 312     @property
 313     def packed(self) -> bytes:
 314         data = self.encode()
 315         payload = self.PROTO + "," + data if data else self.PROTO
 316         return f"[LT*0000000000*{len(payload):04X}*{payload}]".encode()
 317
 318
 319 class UNKNOWN(BeeSurePkt):
 320     pass
 321
 322
 323 class LK(BeeSurePkt):
 324     RESPOND = Respond.INL
 325
 326     def in_decode(self, *args: str) -> None:
 327         numargs = len(args)
 328         if numargs > 1:
 329             self.step = args[1]
 330         if numargs > 2:
 331             self.tumbling_number = args[2]
 332         if numargs > 3:
 333             self.battery_percentage = args[3]
 334
 335     def in_encode(self) -> str:
 336         return "LK"
 337
 338
 339 class CONFIG(BeeSurePkt):
 340     pass
 341
 342
 343 class ICCID(BeeSurePkt):
 344     pass
 345
 346
 347 class _LOC_DATA(BeeSurePkt):
 348     def in_decode(self, *args: str) -> None:
 349         p = SimpleNamespace()
 350         _id = lambda x: x
 351         for (obj, attr, func), val in zip(
 352             (
 353                 (p, "verb", _id),
 354                 (p, "date", _id),
 355                 (p, "time", _id),
 356                 (self, "gps_valid", lambda x: x == "A"),
 357                 (p, "lat", float),
 358                 (p, "nors", lambda x: 1 if x == "N" else -1),
 359                 (p, "lon", float),
 360                 (p, "eorw", lambda x: 1 if x == "E" else -1),
 361                 (self, "speed", float),
 362                 (self, "direction", float),
 363                 (self, "altitude", float),
 364                 (self, "num_of_sats", int),
 365                 (self, "gsm_strength_percentage", int),
 366                 (self, "battery_percentage", int),
 367                 (self, "pedometer", int),
 368                 (self, "tubmling_times", int),
 369                 (self, "device_status", lambda x: int(x, 16)),
 370                 (self, "base_stations_number", int),
 371                 (self, "connect_base_station_number", int),
 372                 (self, "mcc", int),
 373                 (self, "mnc", int),
 374             ),
 375             args[:21],
 376         ):
 377             setattr(obj, attr, func(val))  # type: ignore
 378         rest_args = args[21:]
 379         # (area_id, cell_id, strength)*
 380         self.base_stations = [
 381             tuple(int(el) for el in rest_args[i * 3 : 3 + i * 3])
 382             for i in range(self.base_stations_number)
 383         ]
 384         rest_args = rest_args[3 * self.base_stations_number :]
 385         self.wifi_aps_number = int(rest_args[0])
 386         # (SSID, MAC, strength)*
 387         self.wifi_aps = [
 388             (
 389                 rest_args[1 + i * 3],
 390                 rest_args[2 + i * 3],
 391                 int(rest_args[3 + i * 3]),
 392             )
 393             for i in range(self.wifi_aps_number)
 394         ]
 395         rest_args = rest_args[1 + 3 * self.wifi_aps_number :]
 396         self.positioning_accuracy = float(rest_args[0])
 397         self.devtime = (
 398             datetime.strptime(
 399                 p.date + p.time,
 400                 "%d%m%y%H%M%S",
 401             )
 402             # .replace(tzinfo=timezone.utc)
 403             # .astimezone(tz=timezone.utc)
 404         )
 405         self.latitude = p.lat * p.nors
 406         self.longitude = p.lon * p.eorw
 407
 408
 409 class UD(_LOC_DATA):
 410     pass
 411
 412
 413 class UD2(_LOC_DATA):
 414     pass
 415
 416
 417 class TKQ(BeeSurePkt):
 418     RESPOND = Respond.INL
 419
 420
 421 class TKQ2(BeeSurePkt):
 422     RESPOND = Respond.INL
 423
 424
 425 class AL(_LOC_DATA):
 426     RESPOND = Respond.INL
 427
 428
 429 class CR(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 POWEROFF(BeeSurePkt):
 442     pass
 443
 444
 445 class RESET(BeeSurePkt):
 446     pass
 447
 448
 449 class SOS(BeeSurePkt):
 450     OUT_KWARGS = (("phonenumbers", l3str, ["", "", ""]),)
 451
 452     def out_encode(self) -> str:
 453         self.phonenumbers: List[str]
 454         return ",".join(self.phonenumbers)
 455
 456
 457 class _SET_PHONE(BeeSurePkt):
 458     OUT_KWARGS = (("phonenumber", str, ""),)
 459
 460     def out_encode(self) -> str:
 461         self.phonenumber: str
 462         return self.phonenumber
 463
 464
 465 class SOS1(_SET_PHONE):
 466     pass
 467
 468
 469 class SOS2(_SET_PHONE):
 470     pass
 471
 472
 473 class SOS3(_SET_PHONE):
 474     pass
 475
 476
 477 # Build dicts protocol number -> class and class name -> protocol number
 478 CLASSES = {}
 479 if True:  # just to indent the code, sorry!
 480     for cls in [
 481         cls
 482         for name, cls in globals().items()
 483         if isclass(cls)
 484         and issubclass(cls, BeeSurePkt)
 485         and not name.startswith("_")
 486     ]:
 487         CLASSES[cls.__name__] = cls
 488
 489
 490 def class_by_prefix(
 491     prefix: str,
 492 ) -> Union[Type[BeeSurePkt], List[str]]:
 493     if prefix.startswith(PROTO_PREFIX):
 494         pname = prefix[len(PROTO_PREFIX) :].upper()
 495     else:
 496         raise KeyError(pname)
 497     lst = [name for name in CLASSES.keys() if name.upper().startswith(pname)]
 498     for proto in lst:
 499         if len(lst) == 1:  # unique prefix match
 500             return CLASSES[proto]
 501         if proto == pname:  # exact match
 502             return CLASSES[proto]
 503     return lst
 504
 505
 506 def proto_handled(proto: str) -> bool:
 507     return proto.startswith(PROTO_PREFIX)
 508
 509
 510 def proto_name(obj: Union[MetaPkt, BeeSurePkt]) -> str:
 511     return PROTO_PREFIX + (
 512         obj.__class__.__name__ if isinstance(obj, BeeSurePkt) else obj.__name__
 513     )
 514
 515
 516 def proto_of_message(packet: bytes) -> str:
 517     return PROTO_PREFIX + packet[20:-1].split(b",")[0].decode()
 518
 519
 520 def imei_from_packet(packet: bytes) -> Optional[str]:
 521     toskip, _, imei, _ = _framestart(packet)
 522     if toskip == 0 and imei != "":
 523         return imei
 524     return None
 525
 526
 527 def is_goodbye_packet(packet: bytes) -> bool:
 528     return False
 529
 530
 531 def inline_response(packet: bytes) -> Optional[bytes]:
 532     proto = packet[20:-1].split(b",")[0].decode()
 533     if proto in CLASSES:
 534         cls = CLASSES[proto]
 535         if cls.RESPOND is Respond.INL:
 536             return cls.Out().packed
 537     return None
 538
 539
 540 def probe_buffer(buffer: bytes) -> bool:
 541     return bool(RE.search(buffer))
 542
 543
 544 def parse_message(packet: bytes, is_incoming: bool = True) -> BeeSurePkt:
 545     """From a packet (without framing bytes) derive the XXX.In object"""
 546     toskip, vendor, imei, datalength = _framestart(packet)
 547     payload = packet[20:-1].decode().split(",")
 548     proto = payload[0] if len(payload) > 0 else ""
 549     if proto not in CLASSES:
 550         cause: Union[DecodeError, ValueError, IndexError] = ValueError(
 551             f"Proto {proto} is unknown"
 552         )
 553     else:
 554         try:
 555             if is_incoming:
 556                 return CLASSES[proto].In(vendor, imei, datalength, payload)
 557             else:
 558                 return CLASSES[proto].Out(vendor, imei, datalength, payload)
 559         except (DecodeError, ValueError, IndexError) as e:
 560             cause = e
 561     if is_incoming:
 562         retobj = UNKNOWN.In(vendor, imei, datalength, payload)
 563     else:
 564         retobj = UNKNOWN.Out(vendor, imei, datalength, payload)
 565     retobj.proto = proto  # Override class attr with object attr
 566     retobj.cause = cause
 567     return retobj