{"id":24701629,"url":"https://github.com/pixelweatherproject/pwmp-msg","last_synced_at":"2026-04-17T11:32:43.092Z","repository":{"id":274304628,"uuid":"896625507","full_name":"PixelWeatherProject/pwmp-msg","owner":"PixelWeatherProject","description":"Provides the types representing all messages in the PixelWeather Messaging Protocol.","archived":false,"fork":false,"pushed_at":"2025-03-16T16:36:37.000Z","size":62,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-16T17:19:36.503Z","etag":null,"topics":["esp32","esp32-rust","esp32-wifi","esp32s3","pixelweather","rust","serde-serialization","weather","weather-station"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PixelWeatherProject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-30T21:33:18.000Z","updated_at":"2025-03-07T13:06:56.000Z","dependencies_parsed_at":"2025-01-26T13:29:50.547Z","dependency_job_id":"c69807a8-2d47-4385-a6b5-76e388538cb4","html_url":"https://github.com/PixelWeatherProject/pwmp-msg","commit_stats":null,"previous_names":["pixelweatherproject/pwmp-msg"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PixelWeatherProject%2Fpwmp-msg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PixelWeatherProject%2Fpwmp-msg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PixelWeatherProject%2Fpwmp-msg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PixelWeatherProject%2Fpwmp-msg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PixelWeatherProject","download_url":"https://codeload.github.com/PixelWeatherProject/pwmp-msg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244902924,"owners_count":20529115,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","esp32-rust","esp32-wifi","esp32s3","pixelweather","rust","serde-serialization","weather","weather-station"],"created_at":"2025-01-27T05:24:59.151Z","updated_at":"2026-04-17T11:32:43.062Z","avatar_url":"https://github.com/PixelWeatherProject.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PWMP - Messages library\nThis is a core crate that contains the types which represent all the different message types in the PixelWeather Messaging Protocol *(PWMP)*.\nSerialization and deserialization is also handled by this library.\n\n# Message structure\nA \"message\" is a simple `enum` that can be one of two variants:\n- `Request`\n    - Server requested a resource from the client (node) or vice-versa.\n- `Response`\n    - Contains the resource requested by the other party.\n\nRequests and responses contain deeper level variants.\n\n```mermaid\ngraph TD;\n    Message--\u003eRequest\n    Message--\u003eResponse\n\n    Request-.-\u003ePing\n    Request-.-\u003eHello\n    Request-.-\u003ePostResults\n    Request-.-\u003ePostStats\n    Request-.-\u003eSendNotification\n    Request-.-\u003eGetSetting\n    Request-.-\u003eUpdateCheck\n    Request-.-\u003eNextUpdateChunk\n    Request-.-\u003eReportFirmwareUpdate\n    Request-.-\u003eBye\n\n    Response-.-\u003ePong\n    Response-.-\u003eOk\n    Response-.-\u003eReject\n    Response-.-\u003eFirmwareUpToDate\n    Response-.-\u003eUpdateAvailable\n    Response-.-\u003eUpdatePart\n    Response-.-\u003eUpdateEnd\n    Response-.-\u003eSettings\n```\n\n### Ping test message (`Ping`)\nThe `Pind` message is only used for testing if the connection to the server is alive. The server will respond with a `Pong` message.\n\n### Introduction message (`Hello`)\nThe `Hello` message is the first message sent by the client (node) to the server. It contains the MAC address of the client. The server will respond with an `Ok` message if the client is authorized to communicate with the server.\n\nMessage structure:\n```mermaid\ngraph LR;\n    Hello--\u003eMAC\n```\n\n### Settings request meeting (`GetSettings`)\nThe `GetSettings` message is sent by the client (node) to the server to request the settings for the node. The server will respond with a `Settings` message.\n\nMessage structure:\n```mermaid\ngraph LR;\n    GetSettings--\u003eSN[Setting names...]\n```\n\n### Settings response message (`Settings`)\nThe `Settings` message is sent by the server to the client (node) as a response to a `GetSettings` message. It contains the settings for the node.\n\nMessage structure:\n```mermaid\ngraph LR;\n    Settings--\u003eSV[Setting values...]\n```\n\nThe setting values are in the same order as requested in the `GetSettings` message.\n\n### Results posting message (`PostResults`)\nThe `PostResults` message is sent by the client (node) to the server to post measurement results of the node. The server will respond with an `Ok` message if the results were successfully received.\n\nMessage structure:\n```mermaid\ngraph LR;\n    PostResults--\u003eTemperature\n    PostResults--\u003eHumidity\n    PostResults--\u003eAP[Air Pressure]\n```\n\n### Statistics posting message (`PostStats`)\nThe `PostStats` message is sent by the client (node) to the server to post statistics of the node. The server will respond with an `Ok` message if the statistics were successfully received.\n\nMessage structure:\n```mermaid\ngraph LR;\n    PostStats--\u003eV[Battery Voltage]\n    PostStats--\u003eSSID[WiFi ESSID]\n    PostStats--\u003eRSSI[WiFi RSSI]\n```\n\n# Example communication sequence\n```mermaid\nsequenceDiagram\n    Node-\u003e\u003eServer: Hello (incl. MAC address)\n\n    alt Known MAC, Successful authentication\n        Server-\u003e\u003eNode: Ok\n    else Unknown MAC\n        Server--xNode: Reject\n    end\n    \n    Node-\u003e\u003eServer: GetSettings [...]\n    Server-\u003e\u003eNode: Settings [...]\n    Node-\u003e\u003eServer: PostResults [temperature, humidity, ...]\n    Server-\u003e\u003eNode: Ok\n    Node-\u003e\u003eServer: PostStats (node statistics)\n    Server-\u003e\u003eNode: Ok\n    Node-\u003e\u003eServer: UpdateCheck [current version]\n\n    opt Detected rollback from bad firmware\n        Node-\u003e\u003eServer: ReportFirmwareUpdate [false]\n        Server-\u003e\u003eNode: Ok\n    end\n\n    opt Successfull update\n        Node-\u003e\u003eServer: ReportFirmwareUpdate [true]\n        Server-\u003e\u003eNode: Ok\n    end\n\n    alt Update available\n        Server-\u003e\u003eNode: UpdateAvailable\n        \n        loop Download update\n            Node-\u003e\u003eServer: NextUpdateChunk [chunk size]\n            Server-\u003e\u003eNode: UpdatePart [...]\n        end\n\n        Server-\u003e\u003eNode: UpdateEnd\n    else Already up to date\n        Server-\u003e\u003eNode: FirmwareUpToDate\n    end\n\n    Node-\u003e\u003eServer: Bye\n```\n\nIf the node's MAC address is not in the database, it's not authorized to communicate with the server.\n```mermaid\nsequenceDiagram\n    Node-\u003e\u003eServer: Hello (incl. MAC address)\n    Server-\u003e\u003eNode: Reject\n```\n\nIt's also possible to configure the server to abruptly close the socket if the device is unauthorized, instead of sending a `Reject` response.\n\n# Message rules\nThe node shall only send **one** `PostResults` message, duplicates will be rejected and the socket will be abruptly closed. The communication between nodes and the server should be exactly as specified in the diagram above. No more messages should be exchanged.\n\nWhen the client (node) is done communicating with the server, it shall **always**:\n1. Send a `Bye` request to the server.\n2. **Wait** until the server closes the connection.\n\nThe [client library](../pwmp-client/) will guarantee the last two two requirements, but not the first one.\n\n# Usage of `Box\u003cT\u003e` types\nMessage variants use `Box\u003c\u003e`-ed types for optimizing the size of messages. Boxed types do not have a capacity property, making them up to 8 bytes smaller than their non-boxed counterparts.\n\n# Limitations\nThe PWMP protocol is designed with the following restrictions:\n- Maximum number of nodes in a network **cannot be more** than $2^{16}$.\n    - This is because node IDs are represented as 16-bit unsigned integers.\n    - A network of more than `65536` nodes would require major optimizations. Using smaller integer types also helps reducing firmware sizes.\n- Messages do not have any kind of error-correcting codes.\n    - Since PWMP uses TCP, there is already some error-correction happening on a lower level.\n    - If a message gets corrupted during transfer, it's very likely that the deserialization would fail anyway.\n\n# Fuzz tests\nYou can run the fuzz tests with `cargo +nightly fuzz run [target]`.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixelweatherproject%2Fpwmp-msg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpixelweatherproject%2Fpwmp-msg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixelweatherproject%2Fpwmp-msg/lists"}