2 Implementation of the protocol "beesure" used by some watch-trackers
3 https://www.4p-touch.com/beesure-gps-setracker-server-protocol.html
6 from datetime import datetime, timezone
8 from inspect import isclass
10 from struct import error, pack, unpack
23 from types import SimpleNamespace
43 MAXBUFFER: int = 65557 # Theoretical max buffer 65536 + 21
44 RE = re.compile(b"\[(\w\w)\*(\d{10})\*([0-9a-fA-F]{4})\*")
47 def _framestart(buffer: bytes) -> Tuple[int, str, str, int]:
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`
53 mo = RE.search(buffer)
67 def __init__(self) -> None:
69 self.imei: Optional[str] = None
72 def recv(self, segment: bytes) -> List[Union[bytes, str]]:
74 Process next segment of the stream. Return successfully deframed
75 packets as `bytes` and error messages as `str`.
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.
82 return [f"More than {MAXBUFFER} unparseable data, dropping"]
83 msgs: List[Union[bytes, str]] = []
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
89 if toskip > 0: # Should not happen, report
91 f"Skipping {toskip} bytes of undecodable data"
92 f' "{self.buffer[:toskip][:64]=!r}"'
94 self.buffer = self.buffer[toskip:]
95 # From this point, buffer starts with a packet header
100 f"Packet's imei {imei} mismatches"
101 f" previous value {self.imei}, old value kept"
103 self.datalen = datalen
104 if len(self.buffer) < self.datalen + 21: # Incomplete packet
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])
111 f"Packet does not end with ']'"
112 f" at {self.datalen+20}: {self.buffer=!r}"
114 self.buffer = self.buffer[self.datalen + 21 :]
118 def close(self) -> bytes:
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)
130 return f"[{vid:2s}*{imei:10s}*{dlen:04X}*".encode() + buffer[20:]
133 ### Parser/Constructor ###
136 class DecodeError(Exception):
137 def __init__(self, e: Exception, **kwargs: Any) -> None:
139 for k, v in kwargs.items():
143 def maybe(typ: type) -> Callable[[Any], Any]:
144 return lambda x: None if x is None else typ(x)
147 def intx(x: Union[str, int]) -> int:
148 if isinstance(x, str):
153 def boolx(x: Union[str, bool]) -> bool:
154 if isinstance(x, str):
155 if x.upper() in ("ON", "TRUE", "1"):
157 if x.upper() in ("OFF", "FALSE", "0"):
159 raise ValueError(str(x) + " could not be parsed as a Boolean")
165 For each class corresponding to a message, automatically create
166 two nested classes `In` and `Out` that also inherit from their
167 "nest". Class attribute `IN_KWARGS` defined in the "nest" is
168 copied to the `In` nested class under the name `KWARGS`, and
169 likewise, `OUT_KWARGS` of the nest class is copied as `KWARGS`
170 to the nested class `Out`. In addition, method `encode` is
171 defined in both classes equal to `in_encode()` and `out_encode()`
177 def __getattr__(self, name: str) -> Any:
180 def __setattr__(self, name: str, value: Any) -> None:
184 cls: Type["MetaPkt"],
186 bases: Tuple[type, ...],
187 attrs: Dict[str, Any],
189 newcls = super().__new__(cls, name, bases, attrs)
190 newcls.In = super().__new__(
195 "KWARGS": newcls.IN_KWARGS,
196 "decode": newcls.in_decode,
197 "encode": newcls.in_encode,
200 newcls.Out = super().__new__(
205 "KWARGS": newcls.OUT_KWARGS,
206 "decode": newcls.out_decode,
207 "encode": newcls.out_encode,
214 NON = 0 # Incoming, no response needed
215 INL = 1 # Birirectional, use `inline_response()`
216 EXT = 2 # Birirectional, use external responder
219 class BeeSurePkt(metaclass=MetaPkt):
220 RESPOND = Respond.NON # Do not send anything back by default
222 IN_KWARGS: Tuple[Tuple[str, Callable[[Any], Any], Any], ...] = ()
223 OUT_KWARGS: Tuple[Tuple[str, Callable[[Any], Any], Any], ...] = ()
224 KWARGS: Tuple[Tuple[str, Callable[[Any], Any], Any], ...] = ()
225 In: Type["BeeSurePkt"]
226 Out: Type["BeeSurePkt"]
230 def __getattr__(self, name: str) -> Any:
233 def __setattr__(self, name: str, value: Any) -> None:
236 def __init__(self, *args: Any, **kwargs: Any):
238 Construct the object _either_ from (length, payload),
239 _or_ from the values of individual fields
241 assert not args or (len(args) == 4 and not kwargs)
242 if args: # guaranteed to be two arguments at this point
243 self.vendor, self.imei, self.datalength, self.payload = args
245 self.decode(*self.payload)
247 raise DecodeError(e, obj=self)
249 for kw, typ, dfl in self.KWARGS:
250 setattr(self, kw, typ(kwargs.pop(kw, dfl)))
253 self.__class__.__name__ + " stray kwargs " + str(kwargs)
256 def __repr__(self) -> str:
257 return "{}({})".format(
258 self.__class__.__name__,
262 'bytes.fromhex("{}")'.format(v.hex())
263 if isinstance(v, bytes)
266 for k, v in self.__dict__.items()
267 if not k.startswith("_")
271 def decode(self, *args: str) -> None:
274 def in_decode(self, *args: str) -> None:
275 # Overridden in subclasses, otherwise do not decode payload
278 def out_decode(self, *args: str) -> None:
279 # Overridden in subclasses, otherwise do not decode payload
282 def encode(self) -> str:
285 def in_encode(self) -> str:
286 # Necessary to emulate terminal, which is not implemented
287 raise NotImplementedError(
288 self.__class__.__name__ + ".encode() not implemented"
291 def out_encode(self) -> str:
292 # Overridden in subclasses, otherwise command verb only
296 def packed(self) -> bytes:
297 buffer = self.encode().encode()
298 return f"[LT*0000000000*{len(buffer):04X}*".encode() + buffer + b"]"
301 class UNKNOWN(BeeSurePkt):
305 class LK(BeeSurePkt):
307 RESPOND = Respond.INL
309 def in_decode(self, *args: str) -> None:
314 self.tumbling_number = args[2]
316 self.battery_percentage = args[3]
318 def in_encode(self) -> str:
322 class CONFIG(BeeSurePkt):
326 class ICCID(BeeSurePkt):
330 class _LOC_DATA(BeeSurePkt):
331 def in_decode(self, *args: str) -> None:
332 p = SimpleNamespace()
334 for (obj, attr, func), val in zip(
339 (self, "gps_valid", lambda x: x == "A"),
341 (p, "nors", lambda x: 1 if x == "N" else -1),
343 (p, "eorw", lambda x: 1 if x == "E" else -1),
344 (self, "speed", float),
345 (self, "direction", float),
346 (self, "altitude", float),
347 (self, "num_of_sats", int),
348 (self, "gsm_strength_percentage", int),
349 (self, "battery_percentage", int),
350 (self, "pedometer", int),
351 (self, "tubmling_times", int),
352 (self, "device_status", lambda x: int(x, 16)),
353 (self, "base_stations_number", int),
354 (self, "connect_base_station_number", int),
360 setattr(obj, attr, func(val)) # type: ignore
361 rest_args = args[21:]
362 # (area_id, cell_id, strength)*
363 self.base_stations = [
364 tuple(int(el) for el in rest_args[i * 3 : 3 + i * 3])
365 for i in range(self.base_stations_number)
367 rest_args = rest_args[3 * self.base_stations_number :]
368 self.wifi_aps_number = int(rest_args[0])
369 # (SSID, MAC, strength)*
372 rest_args[1 + i * 3],
373 rest_args[2 + i * 3],
374 int(rest_args[3 + i * 3]),
376 for i in range(self.wifi_aps_number)
378 rest_args = rest_args[1 + 3 * self.wifi_aps_number :]
379 self.positioning_accuracy = float(rest_args[0])
385 # .replace(tzinfo=timezone.utc)
386 # .astimezone(tz=timezone.utc)
388 self.latitude = p.lat * p.nors
389 self.longitude = p.lon * p.eorw
396 class UD2(_LOC_DATA):
400 class TKQ(BeeSurePkt):
402 RESPOND = Respond.INL
405 class TKQ2(BeeSurePkt):
407 RESPOND = Respond.INL
412 RESPOND = Respond.INL
415 # Build dicts protocol number -> class and class name -> protocol number
418 if True: # just to indent the code, sorry!
421 for name, cls in globals().items()
423 and issubclass(cls, BeeSurePkt)
424 and not name.startswith("_")
426 if hasattr(cls, "PROTO"):
427 CLASSES[cls.PROTO] = cls
428 PROTOS[cls.__name__] = cls.PROTO
433 ) -> Union[Type[BeeSurePkt], List[Tuple[str, str]]]:
436 for name, proto in PROTOS.items()
437 if name.upper().startswith(prefix.upper())
442 return CLASSES[proto]
445 def proto_handled(proto: str) -> bool:
446 return proto.startswith(PROTO_PREFIX)
449 def proto_name(obj: Union[MetaPkt, BeeSurePkt]) -> str:
450 return PROTO_PREFIX + (
451 obj.__class__.__name__ if isinstance(obj, BeeSurePkt) else obj.__name__
455 def proto_of_message(packet: bytes) -> str:
456 return PROTO_PREFIX + packet[20:-1].split(b",")[0].decode()
459 def imei_from_packet(packet: bytes) -> Optional[str]:
460 toskip, _, imei, _ = _framestart(packet)
461 if toskip == 0 and imei != "":
466 def is_goodbye_packet(packet: bytes) -> bool:
470 def inline_response(packet: bytes) -> Optional[bytes]:
471 proto = packet[20:-1].split(b",")[0].decode()
474 if cls.RESPOND is Respond.INL:
475 return cls.Out().packed
479 def probe_buffer(buffer: bytes) -> bool:
480 return bool(RE.search(buffer))
483 def parse_message(packet: bytes, is_incoming: bool = True) -> BeeSurePkt:
484 """From a packet (without framing bytes) derive the XXX.In object"""
485 toskip, vendor, imei, datalength = _framestart(packet)
486 payload = packet[20:-1].decode().split(",")
487 proto = payload[0] if len(payload) > 0 else ""
488 if proto not in CLASSES:
489 cause: Union[DecodeError, ValueError, IndexError] = ValueError(
490 f"Proto {proto} is unknown"
495 return CLASSES[proto].In(vendor, imei, datalength, payload)
497 return CLASSES[proto].Out(vendor, imei, datalength, payload)
498 except (DecodeError, ValueError, IndexError) as e:
501 retobj = UNKNOWN.In(vendor, imei, datalength, payload)
503 retobj = UNKNOWN.Out(vendor, imei, datalength, payload)
504 retobj.PROTO = proto # Override class attr with object attr