{"id":14963871,"url":"https://github.com/boneskull/micropython-watson-iot","last_synced_at":"2025-10-25T03:30:48.742Z","repository":{"id":57441524,"uuid":"104008150","full_name":"boneskull/micropython-watson-iot","owner":"boneskull","description":"Micropython SDK for IBM's Watson IoT Platform","archived":true,"fork":false,"pushed_at":"2018-01-24T04:11:22.000Z","size":50,"stargazers_count":6,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-01T06:12:49.766Z","etag":null,"topics":["device","esp8266","ibm","iot","micropython","pyboard","python","watson"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boneskull.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-19T00:58:27.000Z","updated_at":"2024-11-19T20:02:04.000Z","dependencies_parsed_at":"2022-09-06T02:21:46.940Z","dependency_job_id":null,"html_url":"https://github.com/boneskull/micropython-watson-iot","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fmicropython-watson-iot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fmicropython-watson-iot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fmicropython-watson-iot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fmicropython-watson-iot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boneskull","download_url":"https://codeload.github.com/boneskull/micropython-watson-iot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238071156,"owners_count":19411600,"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":["device","esp8266","ibm","iot","micropython","pyboard","python","watson"],"created_at":"2024-09-24T13:32:15.826Z","updated_at":"2025-10-25T03:30:48.357Z","avatar_url":"https://github.com/boneskull.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# micropython-watson-iot\n\n\u003e Unofficial IBM Watson IoT Platform SDK for Devices Running MicroPython\n\nThis is a \"SDK\" in the loosest sense.\n\n## Installation\n\n**This library is intended to be used with an [ESP32](https://espressif.com/en/products/hardware/esp32/overview)-based device**, or at least something with connectivity that has more RAM than a ESP8266, and runs [MicroPython](https://micropython.org).\n\nThe device you're using should already have been flashed with [MicroPython](https://micropython.org).\n\n### Installation via REPL\n\nOpen a serial terminal, e.g.:\n\n```bash\n$ python3 -m serial.tools.miniterm --raw /dev/your-com-port 115200\n```\n\nEnsure your device has internet connectivity, then:\n\n```python\nimport upip\nupip.install('micropython-watson-iot')\n```\n\nThe above will install the latest release of this module (and its dependencies) within `lib/`. \n\n### Installation via Host Computer\n\nIf for some reason the above doesn't work, you can try to do this manually through various means.\n\n1. Clone [this repo](https://github.com/boneskull/micropython-watson-iot), or download a `.zip`.\n1. From your working copy, copy the `watson_iot/` directory to your device\n1. Create a `lib` directory on your device\n1. Create a `lib/umqtt` directory on your device \n1. Clone [micropython-lib](https://github.com/micropython/micropython-lib) or download a `.zip`\n1. From the `micropython-lib` working copy, put: \n    1. `umqtt.simple/umqtt/simple.py` into `lib/umqtt/simple.py`\n    1. `umqtt.robust/umqtt/robust.py` into `lib/umqtt/robust.py`\n\n#### Using Adafruit's MicroPython Tool\n\nA tool you can use to copy files is [adafruit-ampy](https://github.com/adafruit/ampy), which can be installed via `pip3 install adafruit-ampy`.  \n\nThis oughtta do it: \n\n```bash\n$ PORT=/dev/tty.SLAB_USBtoUART \u0026\u0026 \\\nampy --port \"${PORT}\" put /path/to/micropython-watson-iot/watson_iot \u0026\u0026 \\\nampy --port \"${PORT}\" mkdir lib \u0026\u0026 \\\nampy --port \"${PORT}\" mkdir lib/umqtt \u0026\u0026 \\\nampy --port \"${PORT}\" put \\\n  /path/to/micropython-lib/umqtt.simple/umqtt/simple.py lib/umqtt/simple.py \u0026\u0026 \\\nampy --port \"${PORT}\" put \\\n  /path/to/micropython-lib/umqtt.robust/umqtt/robust.py lib/umqtt/robust.py\n```\n\n(Replace the working copy paths and the value of `PORT` with your device path.)\n\n## IBM Cloud \u0026 Watson IoT Platform\n\nYou have a couple options here.\n\n- To experiment, you can use [Watson IoT Platform Quickstart](https://quickstart.internetofthings.ibmcloud.com/), or\n- [Sign up for a (free) IBM Cloud account](https://console.bluemix.net/registration/), then [create an Watson IoT Platform service](https://console.bluemix.net/catalog/services/internet-of-things-platform) from the catalog\n\n## Usage\n\nIn lieu of proper API documentation, here are a bunch of examples:\n\n### Connecting\n\n```python\nfrom watson_iot import Device\n\nmy_device = Device(\n    device_id='my-device-id', # required\n    device_type='my-device-type', # required\n    token='my-device-token', # required\n    # optional parameters shown with defaults below\n    org='quickstart', \n    username='use-token-auth',\n    port=8883, # this is 1883 if default `org` used\n    clean_session=True,\n    domain='internetofthings.ibmcloud.com',\n    ssl_params=None,\n    log_level='info'\n)\n\nmy_device.connect()\n```\n\nWhen finished, you can disconnect:\n\n```python\nmy_device.disconnect()\n```\n\n### Publishing an Event\n\nAssuming the Device is connected, this example will publish a single event with ID `my_event_id`.\n\n```python\nmy_device.publishEvent(\n    'my_event_id', # event name\n    {'ok': True}, # message payload\n    \n    message_format='json', # 'text' is also built-in\n    qos=0 # QoS 0 or QoS 1\n)\n```\n\n### Handling a Command\n\nThe following will execute the `my_handler` function when command `my-command` is received by the Device.\n\n```python\ndef my_handler(message):\n  \"\"\"\n  does something with `message`\n  \"\"\"\n  pass\n\nmy_device.set_command('my-command', my_handler)\n\n# blocking wait for command\nwhile my_device.is_connected:\n    my_device.sync_loop()\n```\n\nAlternatively, a non-blocking approach:\n\n```python\nimport utime as time\n\n# non-blocking wait for command\nwhile my_device.is_connected:\n    my_device.loop()\n    # do other stuff like sleep\n    time.sleep(1)\n```\n\nTo *stop* handling the command `my-command`:\n\n```python\nmy_device.unset_command('my-command')\n```\n\n### Registering a Custom Message Format\n\n`micropython-watson-iot` comes with built-in encoders and decoders for JSON (`json`) and plain text (`text`) message formats.\n\n**All incoming messages (via commands, for example) are byte literals!** \n\nYou can add a custom encoder and decoder:\n\n```python\ndef to_csv(my_list):\n    \"\"\"\n    `my_list` is likely a list or tuple; returns a str\n    \"\"\"\n    return ','.join(my_list)\n\ndef from_csv(data):\n    \"\"\"\n    `data` is a byte literal and must be coerced to a str first\n    \"\"\"\n    return str(data).split(',')\n    \nmy_device.set_encoder('csv', to_csv)\nmy_device.set_decoder('csv', from_csv)\n```\n\nNow, whenever an event is published with `message_format='csv'`, the *encoder* will modify the outbound message.  Likewise, whenever a command is received in the `csv` format, the incoming message will be run through the *decoder* before it's given to the command handler.\n\nYou can also remove them, if you wish:\n\n```python\nmy_device.unset_encoder('csv')\nmy_device.unset_decoder('csv')\n```\n\n### Potentially Useful Properties\n\n- `is_connected` - `bool`, whether or not the Device is currently connected\n- `is_secure` - `bool`, whether or not the active or inactive connection is encrypted\n\n## Limitations\n\nIf your use case falls outside of the limitations listed below, take a look at [the official Python SDK](https://github.com/ibm-watson-iot/iot-python) instead.  \n\n*That being said*, I'm open to collaboration on the following items, whether they make sense within this project, or others.\n\n### No \"Applications\" Nor \"Gateways\"\n\n`micropython-watson-iot` supports \"unmanaged\" devices only.  A \"device\" in the context of Watson IoT Platform is: \n\n\u003e A device is anything that has a connection to the internet and has data to send to or receive from the cloud. You can use devices to send event information such as sensor readings to the cloud, and to accept commands from applications in the cloud.\n\nThat means you cannot create an [application](https://console.bluemix.net/docs/services/IoT/applications/app_dev_index.html#app_dev_index) or [gateway](https://console.bluemix.net/docs/services/IoT/gateways/gw_dev_index.html#gw_dev_index) with `micropython-watson-iot`.\n\n### No \"Managed Devices\"\n\n`micropython-watson-iot` (as of this writing) does not support [managed devices](https://console.bluemix.net/docs/services/IoT/devices/device_mgmt/index.html#index).\n\nThis may or may not be feasible.\n\n### No XML Support\n\n`micropython-watson-iot` does not (and likely *will not*) parse commands received as XML; nor does it provide any \"helpers\" to publish events as XML.  \n\n### No Support for QoS 2\n\nAs of Sep 20, 2017, the official MicroPython MQTT client module does not support QoS 2, so neither does `micropython-watson-iot`.\n\nI'd be cool with using a *non-official* MQTT client module which *did* support QoS 2, if such a thing existed!\n\n### MicroPython Itself\n\nMicroPython [is not CPython](http://docs.micropython.org/en/latest/pyboard/genrst/index.html).  While MicroPython is *based on* Python 3, `micropython-watson-iot` is not targeting Python 3, nor is it targeting any forks of MicroPython (e.g., [CircuitPython](https://github.com/adafruit/circuitpython)).\n\n## Development Notes\n\n### Publish\n\n```bash\n$ ./setup.py sdist upload\n```\n\nEnter your PyPi pizassword at the pizrompt.\n\n# License\n\n© 2017-2018 [Christopher Hiller](https://boneskull.com).  Licensed Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboneskull%2Fmicropython-watson-iot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboneskull%2Fmicropython-watson-iot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboneskull%2Fmicropython-watson-iot/lists"}