Python库 | misty2py-2.0.2.tar.gz

# Misty2py misty2py is a Python library for Misty II development using [Misty API](https://docs.mistyrobotics.com/misty-ii/rest-api/api-reference/ "Misty Robotics REST API"). ## Features misty2py can be used to: - **perform actions** via sending a `POST` or `DELETE` requests to Misty's API; - **obtain information** via sending a `GET` request to Misty's API; - **receive continuous streams of data** via subscribing to event types on Misty's websockets. misty2py uses following concepts: - **action keywords** - keywords for endpoints of Misty's API that correspond to performing actions; - **information keywords** - keywords for endpoints of Misty's API that correspond to retrieving information; - **data shortcuts** - keywords for commonly used data that is supplied to Misty's API as the body of a `POST` request. ## Usage ### Getting started - Start by making **a new instance** of `Misty`: ```python from misty2py.robot import Misty misty_robot = Misty("0.0.0.0") ``` - Substitute `"0.0.0.0"` with the IP address of your Misty. - Use method `Misty.perform_action()` to tell Misty to **perform an action**. - Use the method `Misty.get_info()` to tell Misty to **return information**. - Use methods `Misty.subscribe_event_type()`, `Misty.unsubscribe_event_type()` and `Misty.get_event_data()` to **obtain continuous streams of data** from Misty's event types. ### Obtaining information Obtaining digital information is handled by `Misty.get_info()` method. `Misty.get_info()` has following arguments: - `info_name` - *required;* the string information keyword corresponding to an endpoint in Misty's API; - `params` - *optional;* a dictionary of parameter name and parameter value, defaults to `{}`. ### Performing actions Performing physical and digital actions including removal of non-system files is handled by `Misty.perform_action()` method. `Misty.perform_action()` has following arguments: - `action_name` - *required;* the string action keyword corresponding to an endpoint in Misty's API; - `data` - *optional;* the data to pass to the request as a dictionary or a data shortcut (string), defaults to `{}`. ### Event types To obtain event data in Misty's framework, it is required to **subscribe** to an event type on Misty's websocket server. Misty's websocket server then streams data to the websocket client, in this implementation via a separate thread. To **access this data,** `Misty.get_event_data()` method must be called from another thread. When data is no longer required to be streamed to the client, an event type can be **unsubscribed** to kill the event thread. #### Subscription Subscribe to an event via `Misty.event("subscribe", **kwargs)` with following keyword arguments: - `type` - *required;* event type string as documented in [Event Types Docs](https://docs.mistyrobotics.com/misty-ii/robot/sensor-data/ "Misty Robotics Event Types"). - `name` - *optional;* a custom event name string; must be unique. - `return_property` - *optional;* the property to return from Misty's websockets; all properties are returned if return_property is not supplied. - `debounce` - *optional;* the interval in ms at which new information is sent; defaults to 250. - `len_data_entries` - *optional;* the maximum number of data entries to keep (discards in fifo style); defaults to 10. - `event_emitter` - *optional;* an event emitter function which emits an event upon message recieval. Supplies the message content as an argument. #### Accessing the data and the log Access the data of an event or its log via `Misty.event("get_data", **kwargs)` or `Misty.event("get_log", **kwargs)` with a keyword argument `name` (the name of the event). #### Unsubscribing Unsubscribe from an event via `Misty.event("unsubscribe", **kwargs)` with a keyword argument `name` (the name of the event). #### Basic example ```python import time from misty2py.robot import Misty m = Misty("0.0.0.0") event = "BatteryCharge" d = m.event("subscribe", type = event) e_name = d.get("event_name") time.sleep(1) d = m.event("get_data", name = e_name) d = m.event("unsubscribe", name = e_name) ``` #### Event emitter usage - example ```python import time from pymitter import EventEmitter from misty2py.robot import Misty m = Misty("192.168.0.103") ee = EventEmitter() event_name = "myevent_001" @ee.on(event_name) def listener(data): print(data) event_type = "BatteryCharge" d = m.event("subscribe", type = event_type, name = event_name, event_emitter = ee) print(d) time.sleep(2) d = m.event("unsubscribe", name = event_name) print(d) ``` ### Utilities The module `misty2py.utils` contains utility functions, including: - `get_random_string(n: int) -> str` - returns an *n* characters long random string containing ASCII letters and digits. This function is especially useful when naming events. - `rgb(red: int, green: int, blue: int) -> dict` - constructs a dictionary of a colour as required by Misty's API from three integers *red*, *green* and *blue* - `construct_transition_dict(data: dict, allowed_data: dict) -> dict` - constructs input to led_trans action from a dict of two colours data dictionaries or shortcuts (under keys col1, col2) and optionally transition time (key time) and transition style (key transition). *allowed_data* is the dictionary of allowed data shortcuts for the particular Misty object the resulting dictionary is planned to be used in. - `file_to_base64_string(fname: str) -> str` - converts a file (an image or a video) into a `base64` string which can be sent via HTTP requests to Misty's API. ### Keywords and shortcuts #### List of supported action keywords - `led` for **post** request to `api/led` endpoint - `led_trans` for **post** request to `api/led/transition` endpoint - `notification_settings` for **post** request to `api/notification/settings` endpoint - `audio_upload` for **post** request `api/audio` to endpoint - `audio_play` for **post** request to `api/audio/play` endpoint - `audio_pause` for **post** request to `api/audio/pause` endpoint - `audio_stop` for **post** request to `api/audio/stop` endpoint - `audio_delete` for **delete** request to `api/audio` endpoint - `audio_record_start` for **post** request to `api/audio/record/start` endpoint - `audio_record_stop` for **post** request to `api/audio/record/stop` endpoint - `audio_disable` for **post** request to `api/services/audio/disable` endpoint - `audio_enable` for **post** request to `api/services/audio/enable` endpoint - `image_upload` for **post** request to `api/images` endpoint - `image_show` for **post** request to `api/images/display` endpoint - `image_settings` for **post** request to `api/images/settings` endpoint - `image_delete` for **delete** request to `api/images` endpoint - `text_show` for **post** request to `api/text/display` endpoint - `text_settings` for **post** request to `api/text/settings` endpoint - `video_upload` for **post** request to `api/videos` endpoint - `video_show` for **post** request to `api/videos/display` endpoint - `video_settings` for **post** request to `api/videos/settings` endpoint - `video_delete` for **delete** request to `api/videos` endpoint - `blink_mapping_delete` for **delete** request to `api/blink/images` endpoint - `slam_enable` for **post** request to `api/services/slam/enable` endpoint - `slam_disable` for **post** request to `api/services/slam/disable` endpoint - `slam_sensors_reset` for **post** request to `api/slam/reset` endpoint - `slam_mapping_start` for **post** request to `api/slam/map/start` endpoint - `slam_mapping_stop` for **post** request to `api/slam/map/stop` endpoint - `slam_map_current` for **post** request to `api/slam/map/current` endpoint - `slam_map_rename` for **post** request to `api/slam/map/rename` endpoint - `slam_infrared_settings`