Metadata-Version: 2.1
Name: imperix
Version: 0.1.4
Summary: Imperix Node SDK including the NodeLink communication handlers that allow robots and drones to communicate with the Imperix streamers and Commander API.
Home-page: https://bitbucket.org/pinetree-ai/imperix-node-sdk-python3
Author: Aptus Engineering Inc.
Author-email: software@aptusai.com
License: UNKNOWN
Description: # Imperix Node SDK - Python
        
        ## Overview
        
        **Imperix** is a new fleet control *philosophy*, not just a *ground control program*. **Imperix** connects an entire fleet to the internet using secured and encrypted communication protocols, and provides a command center interface to all units on the fleet.
        
        The **Imperix Node SDK** is a set of open-source *Software Developer Kits* in common programming languages allowing users to connect and interface custom *autopilot* systems with the **Imperix Cloud**.
        
        The core functionality of the **SDK** includes:
        * Authenticating node with the **Imperix Cloud**
        * Synchronizing mission state with the cloud
        * Streaming manual control commands from the cloud
        * Streaming telemetry, video, and data to the cloud
        
        
        ## Installation
        
        All dependencies for the **Imperix Node SDK** Python implementation are provided in the *requirements.txt* file. To install the dependencies, run the following command:
        
        ```sh
        pip3 install -r requirements.txt
        ```
        
        
        ## Setup
        
        The SDK requires an *environment configuration* file ***.env*** to be placed in the program's root directory. The *environment configuration* requires the following parameters:
        * Unique node identifier string provided upon node registration
        * Node authorization access key provided upon node registration
        * Imperix Commander API URL (standard)
        * Streamer/Stream Controller IP address/URL available in fleet manager
        
        The ***.env*** file may be downloaded from the Imperix Commander node configuration page.
        
        
        ## Usage
        
        The **Imperix Node SDK** is designed to authenticate the node and initialize communications in its own thread. Review detailed SDK documentation available on: https://docs.imperix.ai.
        
        To use the SDK functions, import the SDK into your Python workspace/project using:
        
        ```python
        import asyncio
        from imperix import NodeLink
        ```
        
        ### Async/Await Operations
        
        The NodeLink handlers and communication threads use the **asyncio** package's ***async/await*** calls for concurrent operations. In order to set this up correctly, an event loop must be created and handled.
        
        See the example below for a main file definition:
        
        ```python
        # Developed by Aptus Engineering, Inc. <https://aptus.aero>
        # See LICENSE.md file in project root directory
        
        import asyncio
        from imperix import NodeLink
        
        
        # Set up callback functions
        # Called when mission is updated
        async def missionUpdateCallback(mission):
            print(mission)
        
        
        # Called with manual control command is received
        async def manualControlCallback(control):
            print(control)
        
        
        # Instantiate node link with callbacks
        node = NodeLink(
            missionUpdateCallback=missionUpdateCallback,
            manualControlCallback=manualControlCallback
        )
        
        
        async def main():
            
            # Connect and authenticate
            await node.connect()
        
            # Main loop...
            while True:
                await asyncio.sleep(1)
                print("hello")
        
        
        # Start event loop
        eventLoop = asyncio.get_event_loop()
        
        try:
            asyncio.ensure_future(main())               # Main thread
            asyncio.ensure_future(node.coroutine())     # NodeLink coroutine
            eventLoop.run_forever()
        
        except KeyboardInterrupt:
            pass
        
        finally:
            eventLoop.close()
        
        asyncio.get_event_loop().run_until_complete(NodeLinkThread(node))
        asyncio.get_event_loop().run_forever()
        ```
        
        
        ### Initialization and Recieve Commands
        
        Initialize a communication stream with the **Imperix Cloud** using the following command:
        
        ```python
        node = NodeLink(
            missionUpdateCallback=handleMissionUpdate,
            manualControlCallback=handleManualControl
        )
        ```
        
        Where:
        * **handleMissionUpdate** is a callback/lambda function which accepts the updated mission as a dictionary.
        * **handleManualControl** is a callback/lambda function which accepts manual control command as a dictionary.
        
        Ensure that **node.coroutine()** is called in ***asyncio.ensure_future*** or ***asyncio.get_event_loop().run_until_complete***.
        
        ### Sending Mission Updates
        
        In order to update mission parameters, call the function:
        ```python
        await node.updateMission(
            activeWaypoint=wptIdx,
            missionStatus=status
        )
        ```
        
        Where:
        * **wptIdx** is a dict key to the waypoint index the node is currently moving to/on.
        * **status** is a string defining the current mission status. It can be one of:
            * **Standby** if the mission is loaded but not active
            * **Active** if the node is performing the loaded mission.
            * **Complete** if the node successfully finished the mission
            * **Failed:[ERROR]** if the node failed the mission. **[ERROR]** must be replaced with the reason for mission failure 
        
        
        ### Streaming Data
        
        Three kinds of data streams are available to send to the **Imperix Cloud**. Users can send one of:
        * **Telemetry** - live data representing critical node status, such as location, velocities, attitude, etc.
        * **Video/Image** - live or pre-captured video/image feeds for live view on the **Imperix Commander** or for future analytics using **Imperix Intelligence**.
        * **Data** - any JSON-serializable data strings, such as sensor readings, messages etc.
        
        In order to stream telemetry, construct a dictionary with keys indicating the following variables:
        
        * ATT_ROLL (degrees)
        * ATT_PITCH (degrees)
        * ATT_HEADING (degrees)
        * LOC_LATITUDE (degrees)
        * LOC_LONGITUDE (degrees)
        * LOC_ALTITUDE (meters)
        * VEL_GROUNDSPEED (meters per second)
        * VEL_AIRSPEED (meters per second)
        * VEL_VERTICAL_SPEED (meters per second)
        * VEL_ROLL_RATE (degrees per second)
        * VEL_PITCH_RATE (degrees per second)
        * VEL_YAW_RATE (degrees per second)
        * STS_BATTERY (percentage 0-100)
        * STS_SIGNAL (percentage 0-100)
        
        And call the function:
        
        ```python
        await node.transmitTelemetry(telemetry)
        ```
        
        Where **telemetry** is the dict with the above variables.
        
        In order to stream video/image, either provide the image as a 1 or 3 channel numpy array to the function:
        
        ```python
        await node.transmitImage(
            image,
            timeStamp=timestamp,
            feed=feed
        )
        ```
        
        Where:
        * **image** is the numpy image,
        * **timestamp** is a *datetime* object, or *None* to use current timestamp (live feed), and
        * **feed** is a string identifying the name of the video feed. Default is *PRIMARY*.
        
        A pre-compressed JPEG image binary (avaiable using OpenCV, or Pillow) can also be streamed by calling the function:
        
        ```python
        await node.transmitImageBinary(
            image,
            timeStamp=timestamp,
            feed=feed
        )
        ```
        
        Where **image** is the pre-compressed JPEG image binary as a **bytes** object.
        
        Finally, to stream data to the **Imperix Cloud**, the following function may be called:
        
        ```python
        await node.transmitData(data)
        ```
        
        Where **data** is a dictionary with JSON-serializable keys-value pairs.
        
        ### Ending Session
        
        In order to close out of a session - to be used when disconnecting the node, performing updates, or shutting down the node, the following function may be called:
        
        ```python
        await node.disconnect()
        ```
        
        Shutting down the node, or exiting the program also automatically disconnects the node from the **Imperix Cloud**.
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
