# aws-iot-device-client-python
The AWS IoT Device Client provides device-side functionality for AWS IoT services such as jobs, device shadow, and simple pubsub.
## Installation
### Minimum Requirements
- Python 3.6+
### Install from PyPI
```shell
python3 -m pip install awsiotclient
```
### Install from source
```shell
git clone https://github.com/whill-labs/aws-iot-device-client-python
python3 -m pip install ./aws-iot-device-client-python
```
## Usage
### Create MQTT connection
```python
from awsiotclient import mqtt
# Construct connection parameters
conn_params = mqtt.ConnectionParams()
# Required params
conn_params.endpoint = <your_endpoint_url>
conn_params.cert = <path_to_your_certificate>
conn_params.key = <path_to_your_private_key>
conn_params.root_ca = <path_to_your_root_ca>
# Optional params
conn_params.client_id = <client_id> # default "mqtt-" + uuid4()
conn_params.signing_region = <signing_region> # default "ap-northeast-1" (Tokyo Region)
conn_params.use_websocket = <True/False> # default False
# Initialize connection
mqtt_connection = mqtt.init(conn_params)
connect_future = mqtt_connection.connect()
connect_future.result()
```
### Use AWS IoT named shadow
Note that usage of classic shadow client is similar to named shadow client.
#### without delta (one-way communication from device to cloud)
```python
from awsiotclient import mqtt, named_shadow
# <create mqtt connection here as described above>
my_client = named_shadow.client(
mqtt_connection,
thing_name="my_thing",
shadow_name="my_shadow"
)
my_value = dict(foo="var")
my_clinet.change_reported_value(my_value)
```
#### with delta (two-way communication from/to device and cloud)
```python
from awsiotclient import mqtt, named_shadow
def my_delta_func(thing_name: str, shadow_name: str, value: Dict[str, Any]) -> None:
print("my_client invokes this callback when it receives delta message")
print(f"thing_name: {thing_name}, shadow_name: {shadow_name}, value: {value}")
# <create mqtt connection here as described above>
my_client = named_shadow.client(
mqtt_connection,
thing_name="my_thing",
shadow_name="my_shadow",
delta_func=my_delta_func,
)
my_value = dict(foo="var")
my_client.change_reported_value(my_value)
# <wait until the client receives delta>
```
### Use AWS IoT jobs
```python
from awsiotclient import mqtt, named_shadow
def job_runner(id: str, document: dict):
print("my_client invokes this callback when it receives job document")
print(f"job id: {id}, document: {document}")
# <create mqtt connection here as described above
job_client = jobs.client(
mqtt_connection,
thing_name="my_thing",
job_func=job_runner
)
# <wait until the client receives job>
```
## License
This library is licensed under the Apache 2.0 License.
## Acknowledgments
- [AWS IoT Device SDK v2 for Python](https://github.com/aws/aws-iot-device-sdk-python-v2)
