JAAM WebSocket client - instructions for an AI assistant
=========================================================

You are asked to write a client for the JAAM data server WebSocket API.
Follow every rule below. Violations get the device, and then its IP address,
blocked. The block is silent: the connection just stops receiving data or is
closed, with no reason given. Abuse of the API is punished.

1. ENDPOINT
-----------
- URL: ws://ws.jaam.net.ua/data_fusion_v1  (port 80; wss:// on 443 also works)
- No authentication.

2. KEEP THE CONNECTION OPEN
---------------------------
- The point of a WebSocket is ONE long-lived connection: the server pushes updates when data
  changes. Connect once and keep the connection open.
- Do NOT close the connection after receiving the initial data. Do NOT use the WebSocket as a
  replacement for polling (connect -> read -> disconnect -> repeat later). That is abuse and gets blocked.
- If the task only needs data occasionally, use the REST API (section 7) at the allowed rate instead.
- Close the connection only when it really failed or the application is shutting down.

3. FIRST PACKET (REQUIRED)
--------------------------
Immediately after the handshake the CLIENT sends these text messages, in this order:

  chip_id:<ID>            required, e.g.  chip_id:A1B2C3D4E5F6
  firmware:<version>      required, e.g.  firmware:2.4.1
  user_info:<JSON>        optional, e.g.  user_info:{"chip":"ESP32-S3"}

Rules:
- Format is "<key>:<value>"; the delimiter is the first colon.
- chip_id and firmware MUST both be sent within 10 seconds of connecting.
  Otherwise the server closes the connection and sends no data.
- chip_id must be unique and STABLE for the device (for ESP32: MAC address, uppercase,
  no separators). Never generate a random one per run, never reuse someone else's.
- No newlines inside values.
- user_info JSON: only the "chip" field is used (ESP32, ESP32-S3, ESP32-C3). Optional.
- After the first packet the client does not need to send anything else.

4. WHAT THE SERVER SENDS (overview)
------------------------
Binary frames, little-endian. The first byte is the message type:

  0xA1 alerts   0xA2 notifications   0xA3 weather   0xA4 power grid
  0xA5 radiation   0xA6 beta firmware versions   0xA7 stable firmware versions

Initial data order: alerts, weather, grid, radiation, firmware versions. Updates
follow whenever data changes. IGNORE unknown message types; never drop the
connection because of one.

4a. PACKET FORMAT AND PARSING
----------------------------
All numbers are little-endian. Message = [type: 1 byte][body]. The body is a sequence of
fixed-size records. region_id is a u16 numeric region id (e.g. 31 = Kyiv city); radiation also
uses 8888 for Prypiat.

  0xA1 alerts: body = hash_actual u16, hash_previous u16, then records (region_id u16, flags u16)
       first packet = FULL state, later packets = ONLY changed regions
  0xA2 notifications: records (region_id u16, flags u16). An EVENT, not a state.
  0xA3 weather: records (region_id u16, temp u8)            full state
  0xA4 power grid: records (region_id u16, state u8)        full state
  0xA5 radiation: records (region_id u16, value u16)        full state
  0xA6 beta / 0xA7 stable firmware: records (major u8, minor u8, patch u8, beta u16)
       beta == 0 -> stable "major.minor.patch", else beta "major.minor.patch-b<beta>"

Alerts flags (bit numbers): 0 air alert, 1 artillery, 2 urban fights, 3 chemical, 4 nuclear,
5 drones, 6 missile, 11 level yellow, 12 level red.
- flags == 0 for a region means the alert ENDED: remove it from your state.
- A region absent from a packet is unchanged.
- Integrity: hash_actual = sum of the bytes of the packet's records mod 65536; hash_previous = the
  hash_actual of the previous packet. If a new packet's hash_previous != the last received
  hash_actual, a packet was missed: the alert state is untrustworthy, so reconnect (with backoff) to
  get the full state. Do NOT check the very first packet after connecting; just remember its hash_actual.

Notification flags: bit 5 drone, 6 rocket, 7 KAB, 8 ballistic, 9 explosion, 10 recon drone.
Show them for a while, do not store them as state.

Weather temp (u8): bit 7 = sign (1 = negative), bits 0-6 = magnitude. 25 -> +25, 140 (0x8C) -> -12.
0 can mean 0 C or "no data".
Power grid state: a code from the source (Ukrenergo), passed through unchanged. Show unknown codes as
"unknown", never as "all fine".
Radiation value: integer background level (0-2000), the maximum in the region.

Parsing rules: check body length is a multiple of the record size, else skip the frame (do not crash,
do not drop the connection). Ignore unknown types. A later packet overwrites an earlier state of
the same region.

Reference parser (verified against packets built by the server):

    import struct

    ALERT_FLAGS = {
        0: "air", 1: "artillery", 2: "urban_fights", 3: "chemical", 4: "nuclear",
        5: "drones", 6: "missile", 11: "level_yellow", 12: "level_red",
    }
    NOTIFY_FLAGS = {5: "drone", 6: "rocket", 7: "kab", 8: "ballistic", 9: "explosion", 10: "recon_drone"}


    def _pairs(body: bytes, fmt: str):
        size = struct.calcsize(fmt)
        if len(body) % size:
            raise ValueError("bad length")
        return list(struct.iter_unpack(fmt, body))


    def decode_temp(mask: int) -> int:
        return -(mask & 0x7F) if mask & 0x80 else mask


    class State:
        def __init__(self):
            self.alerts, self.weather, self.grid, self.radiation = {}, {}, {}, {}
            self.beta, self.stable = [], []
            self.last_hash = None  # hash_actual останнього пакета тривог

        def feed(self, msg: bytes):
            """Повертає False, якщо треба перепідключитись (пропущено пакет тривог)."""
            if not msg:
                return True
            kind, body = msg[0], msg[1:]
            try:
                if kind == 0xA1:
                    h_actual, h_prev = struct.unpack("<HH", body[:4])
                    records = _pairs(body[4:], "<HH")
                    initial = self.last_hash is None
                    if not initial and h_prev != self.last_hash:
                        return False  # пропущено пакет - стан тривог недостовірний
                    for rid, flags in records:
                        if flags:
                            self.alerts[rid] = flags
                        else:
                            self.alerts.pop(rid, None)
                    self.last_hash = h_actual
                elif kind == 0xA3:
                    self.weather.update({rid: decode_temp(m) for rid, m in _pairs(body, "<HB")})
                elif kind == 0xA4:
                    self.grid.update(_pairs(body, "<HB"))
                elif kind == 0xA5:
                    self.radiation.update(_pairs(body, "<HH"))
                elif kind in (0xA6, 0xA7):
                    versions = []
                    for ma, mi, pa, beta in _pairs(body, "<BBBH"):
                        versions.append(f"{ma}.{mi}.{pa}" + (f"-b{beta}" if beta else ""))
                    (self.beta if kind == 0xA6 else self.stable)[:] = versions
                elif kind == 0xA2:
                    return [(rid, [n for b, n in NOTIFY_FLAGS.items() if f >> b & 1]) for rid, f in _pairs(body, "<HH")]
            except (ValueError, struct.error):
                pass  # битий кадр ігноруємо, з'єднання не рвемо
            return True

5. PING / PONG
--------------
- The SERVER sends a WebSocket ping every 20 s and expects a pong within 20 s,
  otherwise it closes the connection.
- These are standard WebSocket control frames. Use a library that answers pings
  automatically, and make sure the read loop is never blocked (a blocked loop means
  no pong). Do NOT emulate pong with a text message. Do not send your own pings
  more often than every 20 s (not needed).
- If no data and no ping arrive for a long time, treat the connection as dead and reconnect.

6. RECONNECTION (MOST COMMON CAUSE OF BANS)
-------------------------------------------
Never reconnect immediately in a loop. Required:
- Exponential backoff between attempts: 5 s, 10 s, 20 s, 40 s, ... capped at 300 s.
- Add random jitter of +-20% to every delay.
- Reset the delay to 5 s only if the previous connection lasted at least 60 s.
  A connection that closed after a few seconds is a failure, not a success.
- Exactly one connection per device. Never open parallel connections.
- After a rejection or a close with code 1008, do not retry immediately: jump to the maximum delay.
- When the network (Wi-Fi) is down, wait for it to come back instead of retrying in a tight loop.

7. REST API (if the task needs it)
----------------------------------
Base URL: https://jaam.net.ua  (JSON, no authentication)
- /alerts_statuses_v3.json  compact: {"states": {"<region>": true|false}}
- /alerts_statuses_v1.json, /alerts_statuses_v2.json  other formats
- /weather_statuses_v1.json, /weather_statuses_v2.json
- /api_status.json  seconds since each source was last updated
- explosives_/missiles_/drones_/kabs_statuses_*.json return 410 Gone. Do not use them.
Rules: poll one endpoint no more often than once per 30 s. Prefer the WebSocket for
real-time updates instead of frequent polling. On errors (5xx, timeout) retry with
increasing delay. Send a meaningful User-Agent.

8. REFERENCE IMPLEMENTATION (Python, websockets library)
--------------------------------------------------------
import asyncio, random, time
import websockets

URL = "ws://ws.jaam.net.ua/data_fusion_v1"
CHIP_ID = "A1B2C3D4E5F6"
FIRMWARE = "my-client-1.0"

async def run():
    delay = 5
    while True:
        started = time.monotonic()
        try:
            # the server pings, the library answers pong
            async with websockets.connect(URL, ping_interval=None) as ws:
                await ws.send(f"chip_id:{CHIP_ID}")
                await ws.send(f"firmware:{FIRMWARE}")
                state = State()  # the parser class from section 4a
                async for message in ws:
                    if isinstance(message, bytes) and state.feed(message) is False:
                        break  # a packet was missed: reconnect with backoff
        except (OSError, websockets.ConnectionClosed):
            pass
        if time.monotonic() - started > 60:
            delay = 5
        await asyncio.sleep(delay * random.uniform(0.8, 1.2))
        delay = min(delay * 2, 300)

asyncio.run(run())

9. ATTRIBUTION
--------------
If the code is part of an app, site, bot or firmware shown to users, it must state clearly where
the data comes from, e.g. "Data: JAAM (jaam.net.ua)" with a link to https://jaam.net.ua, placed
where the user sees the data (site footer, "About" screen, project description).

10. CHECKLIST - VERIFY BEFORE DELIVERING THE CODE
------------------------------------------------
[ ] connection kept open, WebSocket not used as polling
[ ] chip_id then firmware sent first, within 10 s
[ ] chip_id stable and unique
[ ] pings answered; read loop never blocked
[ ] exponential backoff with jitter, reset only after a 60 s+ connection
[ ] one connection per device
[ ] unknown message types and malformed frames ignored
[ ] alert hash chain (hash_previous == last hash_actual) checked; reconnect on a gap
[ ] REST polled at most once per 30 s, or replaced by the WebSocket
[ ] the application/site states that the data comes from JAAM (jaam.net.ua)