MeTIOT 0.1.3__tar.gz

metiot-0.1.3/.gitignore

@@ -0,0 +1,26 @@
+venv/
+**/build*/
+
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake 
+install_manifest.txt
+
+*.o
+*.obj
+*.lo
+*.la
+*.d
+*.a
+*.so
+*.dylib
+*.dll
+*.pyd
+
+*.pyc
+*.pyo
+dist/
+*.egg-info/
+
+*~
+.vscode/

metiot-0.1.3/CMakeLists.txt

@@ -0,0 +1,18 @@
+cmake_minimum_required(VERSION 3.10)
+project(MeTIOTPythonLibrary LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+include(FetchContent)
+FetchContent_Declare(
+    pybind11
+    GIT_REPOSITORY https://github.com/pybind/pybind11.git
+    GIT_TAG        v3.0.1
+)
+FetchContent_MakeAvailable(pybind11)
+
+add_subdirectory(src/MeTIOTCommunication)
+
+add_subdirectory(src/python_bindings)

metiot-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Microelectronic Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metiot-0.1.3/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.2
+Name: MeTIOT
+Version: 0.1.3
+Summary: Communication handling for all MeT IOT devices
+Author-Email: Cody Jackson <cjackson@micr.com.au>
+Project-URL: Homepage, https://github.com/Microelectronic-Technologies/MeTIOTCommunication
+Project-URL: API Reference, https://github.com/Microelectronic-Technologies/MeTIOTCommunication/blob/main/docs/API_REFERENCE.md
+Project-URL: Library Guide, https://github.com/Microelectronic-Technologies/MeTIOTCommunication/blob/main/docs/PYTHON_LIB_GUIDE.md
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# MeT IOT Communication
+
+## Useful Links
+
+* [API Reference](https://github.com/Microelectronic-Technologies/MeTIOTCommunication/blob/main/docs/API_REFERENCE.md)
+* [Python Library Guide](https://github.com/Microelectronic-Technologies/MeTIOTCommunication/blob/main/docs/PYTHON_LIB_GUIDE.md)
+* [Example Projects](https://github.com/Microelectronic-Technologies/MeTIOTCommunication/tree/main/examples)
+
+## Changelog `v0.1.3`
+
+```plaintext
+- Fix invalid pointer error on python program exit
+```
+
+## How To Use
+
+### Importing the Library
+
+#### Use pip to install the library
+
+```sh
+pip install MeTIOT
+```
+
+> [!NOTE]
+> This library is not pre-compiled.
+> You must have installed on your system (Other version may work but are official unsupported):
+> * GCC >= 15.2.1
+> * CMake >= 3.10
+
+### Programming with the Library
+
+#### Testing the library imported successfully
+
+You can use this code to test you can successfully import the library into your code.
+
+```py
+import MeTIOT
+
+client = MeTIOT.DeviceClient("0.0.0.0", 12345)
+
+print(type(client))
+print("MeTIOT import successful!")
+```
+
+#### Using the library
+
+For further information on how to use this library refer to the [PYTHON_LIB_GUIDE.md document](https://github.com/Microelectronic-Technologies/MeTIOTCommunication/blob/main/docs/PYTHON_LIB_GUIDE.md).
+
+## How to compile and use from this repository
+
+Linux based systems:
+
+1. Clone the repository
+```bash
+git clone https://github.com/Microelectronic-Technologies/MeTIOTCommunication.git
+```
+2. Create and navigate into build directory
+```bash
+mkdir build
+cd build
+```
+3. Compile library using CMake
+```bash
+cmake ..
+cmake --build . --config Release
+```
+4. Export path to python
+```bash
+export PYTHONPATH=./src/python_bindings:$PYTHONPATH
+```
+5. Now you can use and import the library in your current directory
+6. *(optional)* Test the library is python
+```bash
+python3
+```
+```py
+import MeTIOT
+client = MeTIOT.DeviceClient("0.0.0.0", 12345)
+type(client)
+client.connect()
+```
+

metiot-0.1.3/README.md

@@ -0,0 +1,83 @@
+# MeT IOT Communication
+
+## Useful Links
+
+* [API Reference](https://github.com/Microelectronic-Technologies/MeTIOTCommunication/blob/main/docs/API_REFERENCE.md)
+* [Python Library Guide](https://github.com/Microelectronic-Technologies/MeTIOTCommunication/blob/main/docs/PYTHON_LIB_GUIDE.md)
+* [Example Projects](https://github.com/Microelectronic-Technologies/MeTIOTCommunication/tree/main/examples)
+
+## Changelog `v0.1.3`
+
+```plaintext
+- Fix invalid pointer error on python program exit
+```
+
+## How To Use
+
+### Importing the Library
+
+#### Use pip to install the library
+
+```sh
+pip install MeTIOT
+```
+
+> [!NOTE]
+> This library is not pre-compiled.
+> You must have installed on your system (Other version may work but are official unsupported):
+> * GCC >= 15.2.1
+> * CMake >= 3.10
+
+### Programming with the Library
+
+#### Testing the library imported successfully
+
+You can use this code to test you can successfully import the library into your code.
+
+```py
+import MeTIOT
+
+client = MeTIOT.DeviceClient("0.0.0.0", 12345)
+
+print(type(client))
+print("MeTIOT import successful!")
+```
+
+#### Using the library
+
+For further information on how to use this library refer to the [PYTHON_LIB_GUIDE.md document](https://github.com/Microelectronic-Technologies/MeTIOTCommunication/blob/main/docs/PYTHON_LIB_GUIDE.md).
+
+## How to compile and use from this repository
+
+Linux based systems:
+
+1. Clone the repository
+```bash
+git clone https://github.com/Microelectronic-Technologies/MeTIOTCommunication.git
+```
+2. Create and navigate into build directory
+```bash
+mkdir build
+cd build
+```
+3. Compile library using CMake
+```bash
+cmake ..
+cmake --build . --config Release
+```
+4. Export path to python
+```bash
+export PYTHONPATH=./src/python_bindings:$PYTHONPATH
+```
+5. Now you can use and import the library in your current directory
+6. *(optional)* Test the library is python
+```bash
+python3
+```
+```py
+import MeTIOT
+client = MeTIOT.DeviceClient("0.0.0.0", 12345)
+type(client)
+client.connect()
+```
+

metiot-0.1.3/docs/API_REFERENCE.md

@@ -0,0 +1,138 @@
+# API Reference
+
+The `MeTIOT` library provides a high-level interface for interacting with MeTIOT IoT devices via TCP. The core of the library is the `DeviceClient`, which manages the connection, event loops, and protocol handling.
+
+## 1. Client Library Components (`MeTIOT`)
+
+The `DeviceClient` class is the primary entry point for all device interactions.
+
+### Lifecycle Management
+
+#### `DeviceClient(ip: str, port: int)`
+
+*Constructor* | **Module:** `MeTIOT`
+
+Initializes the client object with the target device's network information.
+
+* **Arguments**
+    * `ip` (str): IPv4 address of the device.
+    * `port` (int): Communication port.
+* **Errors:** Raises `SocketError` if the IP address is invalid or unsupported.
+
+#### `connect()`
+
+*Method* | **Module:** `MeTIOT.DeviceClient`
+
+Establishes the TCP connection and performs initial handshake/device discovery.
+
+* **Errors:** Raises `SocketError` if the device is unreachable.
+
+#### `disconnect()`
+
+*Method* | **Module:** `MeTIOT.DeviceClient`
+
+Safely closes the active TCP connection.
+
+---
+
+### Protocol & Identity
+
+#### `get_protocol_handler()`
+
+*Method* | **Module:** `MeTIOT.DeviceClient`
+
+Returns the `ProtocolHandler` specific to the current device type. use this to encode/decode bytes.
+
+* **Returns:** `ProtocolHandler`
+
+> [!TIP]
+> Use this instead of the deprecated `get_specific_protocol_handler()`
+
+#### `get_unique_id()`
+
+*Method* | **Module:** `MeTIOT.DeviceClient`
+
+Retrieves the globally unique 64-bit ID assigned to the hardware.
+
+* **Returns:** 8-byte Device ID.
+
+#### `get_device_type()`
+
+*Method* | **Module:** `MeTIOT.DeviceClient`
+
+Identifies the model/type of the connected device.
+
+* **Returns:** `MeTIOT.DeviceType`
+
+---
+
+### Asynchronous Operations
+
+#### `assign_handlers(on_data, on_warning=None, on_fatal=None)`
+
+*Method* | **Module:** `MeTIOT.DeviceClient`
+
+Registers callback functions for the background listening thread.
+
+| Argument | Signature | Description |
+|-|-|-|
+| `on_data` | `(device, header, data)` | Triggered on successful packet reception. |
+| `on_warning` | `(device, msg)` | **Optional.** Triggered on non-fatal issues (e.g., CRC mismatch). |
+| `on_fatal` | `(device, msg)` | **Optional.** Triggered when the loop crashes or 10 warnings occur |
+
+#### `start_listening()`
+
+*Method* | **Module:** `MeTIOT.DeviceClient`
+
+Spawns a background thread to monitor the TCP socket. **Requires handlers to be assigned first.**
+
+* **Errors:** `LibraryError` if `assign_handlers` has not been called.
+
+#### `send_packet(packet: bytes)`
+
+*Method* | **Module:** `MeTIOT.DeviceClient`
+
+Sends a raw byte buffer to the device.
+
+* **Arguments:** `packet` (bytes): The encoded payload.
+* **Errors:** `SocketError` on transmission failure.
+
+
+> [!IMPORTANT]
+> **WIP** Document. Below text may not be correct.
+
+## 2. Protocol Handler Methods (Accessed via `client.get_protocol_handler()`)
+
+The methods available on the protocol handler instance depend entirely on the connected device type. The protocol handler also contains universal utility methods for packet handling.
+
+### 2.1 Universal Protocol Utility Methods
+
+| Method | Returns | Description |
+|-|-|-|
+| `deconstruct_packet(packet: bytes)` | `tuple[int, bytes]` | Decodes the packet buffer, validating CRC, performing COBS unstuffing, and returning the Data Header and raw Data Payload. |
+| `interpret_data(data_payload: bytes)` | `dict` | Interprets the raw Data Payload into a key-value dictionary using known Sub-Headers and Data Types. Keys match the Data Field purpose (e.g., "Temperature_C"). |
+| `fetch_last_packet()` | `bytes` | Returns the raw byte buffer of the last packet successfully created by this protocol handler instance. Useful for re-sending after a `MalformedPacketNotification`. |
+
+### 2.2 Fish Tank Protocol Methods (`Device ID: 0xFF`)
+
+These methods are available if the device type is "Fish Tank"
+
+| Method | Returns | Purpose | Arguments |
+|-|-|-|-|
+
+## 3. Protocol Constants (`MeTIOT.ProtocolConstants`)
+
+These constants are integers representing the 1-byte Header/Sub-Header codes used in the communication. All constants mentioned here are the exposed constants. In other documentation the codes here are referenced as *Device-to-Library Codes*.
+
+### 3.1 Standard Data Header Codes
+
+| Constant Name | Value | Description |
+|:---|:---|:---|
+| `MalformedPacketNotification` | `0xFF` | Notification for a corrupted/unparsable packet. |
+| `DeviceIdentifier` | `0xFE` | Response from the device containing the Device ID and Unique ID. |
+| `DataTransfer` | `0xFD` | Unsolicited data/status update from the device. |
+
+### 3.2 Fish Tank Data Header Codes
+
+| Constant Name | Value | Description |
+|-|-|-|

metiot-0.1.3/docs/DEVICE_PROTOCOL_DEV_GUIDE.md

@@ -0,0 +1,23 @@
+# Device Protocol
+
+## Current Device Protocol Implementation
+
+**Challenge:** Our `DeviceClient` class's `protocolHandler` is of the type `std::unique_ptr<AbstractProtocol>` which stops us from calling device protocol specific functions (e.g., function to create a calibration packet with specific parameters.)
+
+**Solution:** Ideally the python programmer using this library simply calls the same function to get all of their device specific commands regardless of the device type. The solution to this issue is during the python function call `get_specific_protocol_handler` we automatically resolve exactly what protocol data type we are using (stored in `deviceType` for simplicity) then we dynamically cast the `std::unique_ptr<AbstractProtocol>` type into what ever the device protocol actually is.
+
+## Creating New Device Protocols
+
+> [!NOTE]
+> The above information in `Current Device Protocol Implementation` is important to read to understand *why* you are doing the following
+
+When creating a new device protocol (to support device specific protocol commands) following these steps should lead to success:
+
+1. Add protocol .hpp file to `include/protocol/` and .cpp file to `src/protocol/`.
+2. Create a class inheriting `AbstractProtocol` (This gives access to required functions like `constructPacket`).
+3. Copy a similar workflow to other reference protocols. Function called -> Create data field -> Call constructPacket() -> return packet.
+4. Add your new device type to `enum class DeviceType` in `include/client.hpp`.
+5. Modify the device identification function in `src/client.cpp` to support your new protocol.
+6. Modify `/src/python_bindings/bindings.cpp` to support your new protocol. You need to add support for protocol specific functions as well as support for dynamically casting the `AbstractProtocol` pointer to your Protocol pointer.
+
+> If you want to add more OUTGOING fields or any protocol related header/subheader names add them to `include/protocol/protocol_constants.hpp`.

metiot-0.1.3/docs/PYTHON_LIB_GUIDE.md

@@ -0,0 +1,131 @@
+# Guide - How To Use the Library
+
+This guide provides practical steps for using the MeT IoT Python client library. For details on the underlying packet structure, see [TCP_PROTOCOL_SPEC.md](TCP_PROTOCOL_SPEC.md).
+
+## Installation
+
+The MeT IoT library is *soon to be* available on PyPI.
+
+```sh
+pip install MeTIOT
+```
+
+> [!NOTE]
+> This library is not pre-compiled.
+> You must have installed on your system (Other version may work but are official unsupported):
+> * GCC >= 15.2.1
+> * CMake >= 3.10
+
+## Device Discovery
+
+MeT IoT devices broadcast their presence using Zeroconf (mDNS). The library includes a function to listen for and find available devices on your local network.
+
+1. **WIP**
+
+## Connecting to a Device
+
+Establish a persistent TCP connection and perform the initial device identification handshake.
+
+1. **Create Client:** Create a client with the device's IP & Port.
+    ```py
+    import MeTIOT
+
+    client = MeTIOT.DeviceClient("192.168.1.100", 12345)
+    ```
+2. **Connect:** Use the `connect()` method to connect to the device.
+    ```py
+    client.connect()
+    ```
+    **Behind the Scenes:** After connecting to the TCP socket, the client sends a Device Identification Request and waits for the Device Identifier response. This identifies the device type and its unique ID.
+
+3. **Device Protocol:** For sending and interpreting message you will need a protocol handler.
+    ```py
+    protocol = client.get_protocol_handler()
+    ```
+    **Behind the Scenes:** After the connection has happened and the device type is identified that devices unique protocol class will be assigned to the client. This protocol class comes with its own unique methods. You can find all unique device protocol methods in the [API Reference](API_REFERENCE.md).
+
+## Receiving Data
+
+This library uses a dedicated thread to listen for unsolicited data transfers from the device. You should register callback functions to handle incoming data updates.
+
+> [!NOTE]
+> **Prerequisite:** You must first follow [Connecting to a Device](#connecting-to-a-device) creating a client, connecting, **and** fetching the device protocol.
+
+1. **Define Async Callbacks:** Create a function to process incoming data, warning messages, and fatal errors. You will likely have different data processing function for each device type you expect to handle.
+    ```py
+    def my_update_handler(device, header, data):
+        print(f"Received message from {device.get_unique_id()} with header: {header}")
+
+        match header:
+            case MeTIOT.NodeHeader.General.Data:
+                # Use the protocol handler to interpret the raw bytes into a dictionary
+                deviceProtocol = device.get_protocol_handler()
+                telemetry = deviceProtocol.interpret_data(data)
+                print(f"Temperature: {telemetry['Temperature_C']} C")
+
+            case MeTIOT.NodeHeader.MalformedPacketNotification:
+                print("Device reported a communication error.")
+                # Since the library is stateless, you must track your last
+                # sent packet locally if you wish to re-send it (Recommended).
+
+            # Example of modular expansion for specific devices
+            # case MeTIOT.NodeHeader.FishTank.SpecificAlert:
+            #     print("Fish tank alert!")
+
+            case _:
+                # Handle other commands defined in the API Reference
+                pass
+
+    def warning_handler(device, msg):
+        # This function is optional
+        #
+        # When this function is called the warning handling is already handled by the library. This function is just for debugging.
+        print(f"Device {device.get_unique_id()} has non-fatal warning: {msg}")
+
+    def error_handler(device, msg):
+        # This function is optional
+        #
+        # When this function is called a fatal error has occured and the listening loop has stopped. The device will no longer listen for messages.
+        print(f"Device {device.get_unique_id()} has fatal error: {msg}")
+    ```
+
+2. **Register the Handler/s:** Attach the handler/s to the client instance.
+    ```py
+    # --- To assign all devices the same handler ---
+    client.assign_handlers(on_data=my_update_handler, on_warning=warning_handler, on_fatal=error_handler)
+    # If you do not want to specify an on_warning or on_fatal handler they can both be removed
+    # client.assign_handlers(on_data=my_update_handler)
+
+    #   OR
+    # --- To assign different devices types unique handlers ---
+    #
+    # devType = client.get_device_type() # Fetch the current device type
+    #
+    # if (devType == MeTIOT.DeviceType.FISH_TANK):
+    #     client.assign_handlers(on_data=fish_tank_update_handler, on_warning=warning_handler, on_fatal=error_handler)
+    # elif (devType == MeTIOT.DeviceType.UNKNOWN):
+    #     print("Unknown device type. Assigning generic handler")
+    #     client.assign_handlers(on_data=generic_update_handler, on_warning=warning_handler, on_fatal=error_handler)
+    ```
+    **Behind the Scenes:** The client initiates a background listener thread to monitor the socket. When a message is detected, the library automatically handles the decoding and verification (CRC/COBS). It segregated the payload into its `header` and `data` components and dispatches them directly to your handler.
+
+## Sending Commands
+
+To send a command (like changing a setting), use the client objects protocol handler for high-level command methods.
+
+> [!NOTE]
+> **Prerequisite:** You must first follow [Connecting to a Device](#connecting-to-a-device) creating a client, connecting, **and** fetching the device protocol.
+
+1. **Create Packet:** Use the device-specific methods on the `protocol` object to generate the complete, ready-to-send packet buffer.
+    ```py
+    # Example for sending a calibration command to a Fish Tank device
+    # The protocol method generates the Data Payload + Header + CRC + COBS.
+    packet = protocol.create_fish_tank_calibration()
+    ```
+
+2. **Send Packet:** Supply that packet buffer to the client's send function.
+    ```py
+    client.send_packet(packet)
+    print("Calibration request packet sent.")
+    ```
+    **Behind the Scenes:** The protocol handler wraps your command with mandatory overhead (CRC and COBS encoding), ensuring the device can validate the integrity of the message upon receipt.