{"id":15290862,"url":"https://github.com/azure/iot-central-micropython-client","last_synced_at":"2025-10-20T03:30:52.799Z","repository":{"id":57441503,"uuid":"283519718","full_name":"Azure/iot-central-micropython-client","owner":"Azure","description":"A micropython SDK for connecting devices to Microsoft Azure IoT Central","archived":false,"fork":false,"pushed_at":"2024-03-20T13:26:04.000Z","size":356,"stargazers_count":13,"open_issues_count":4,"forks_count":12,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-01-26T15:03:34.004Z","etag":null,"topics":["iot","iot-central","micropython"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Azure.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-29T14:22:21.000Z","updated_at":"2024-05-21T10:53:12.000Z","dependencies_parsed_at":"2023-07-13T21:40:35.756Z","dependency_job_id":"da314aac-44cb-490e-8ac3-d5167fb38640","html_url":"https://github.com/Azure/iot-central-micropython-client","commit_stats":null,"previous_names":["iot-for-all/iotc-micropython-client"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2Fiot-central-micropython-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2Fiot-central-micropython-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2Fiot-central-micropython-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2Fiot-central-micropython-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Azure","download_url":"https://codeload.github.com/Azure/iot-central-micropython-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237254015,"owners_count":19279969,"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":["iot","iot-central","micropython"],"created_at":"2024-09-30T16:09:48.867Z","updated_at":"2025-10-20T03:30:47.423Z","avatar_url":"https://github.com/Azure.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Azure IoTCentral SDK for MicroPython\n\n[![Join the chat at https://gitter.im/iotdisc/community](https://badges.gitter.im/iotdisc.svg)](https://gitter.im/iotdisc/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![Licensed under the MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/iot-for-all/iotc-micropython-client/blob/master/LICENSE)\n[![PyPI version](https://badge.fury.io/py/micropython-iotc.svg)](https://badge.fury.io/py/micropython-iotc)\n\n### An Azure IoT Central device client library for Micropython.\nThis repository contains code for the Azure IoT Central SDK for Micropython. This enables micropython developers to easily create device solutions that semealessly connect to Azure IoT Central applications.\nIt can run on various boards with some tweaks for low-memory devices.\n\n\n## Prerequisites\n+ Micropython 1.20+ (recommended).\n\n## Import ``iotc``\nWith this release we have moved from upip to mip for installing dependencies.  The iotc and dependencies are in the package.json file in the root or the repo.  The iotc file will now be installed from this GitHub repository rather from PyPi making bug fixes easier for contributors.  The sample main.py has been changed so that it does an install when running if the iotc library is not present.  For a manual install you can use the following.  Be aware that your device will need to have internet access so it may need additional code to setup and connect to wifi.\n\n```py\n# If your device needs wifi before running uncomment and adapt the code below as necessary\n# import network\n# wlan = network.WLAN(network.STA_IF)\n# wlan.active(True)\n# wlan.connect(\"SSID\",\"password\")\n# while not wlan.isconnected():\n#     pass\n# print(wlan.isconnected())\n\ntry:\n    import iotc\nexcept:\n    import mip\n    mip.install('github:Azure/iot-central-micropython-client/package.json')\n    import iotc\n```\n\nThe same commands apply when running through Micropython REPL.\n\n\u003e **NOTE:** we are dropping support for ESP8266/NodeMCU devices.  In testing the code on ESP8266 using 1.20.0 of Micropython the device continuously triggers the watchdog timers (WDT) on registration of the device.  In the past we have managed to work around the agressive WDT issues.  Given that the ESP32 is a far more capable device we suggest the use of ESP32 over ESP8622.\n\n\u003e **NOTE:** we have switched our primary testing device to be the Raspberry Pi Pico W as it is widly available and a great device for doing Micropython development.  See: [Raspberry Pi Pico Getting started](https://projects.raspberrypi.org/en/projects/getting-started-with-the-pico).  The tested version of Micropython on the Raspberry Pi Pico W was v1.20.0 [release notes](https://github.com/micropython/micropython/releases/tag/v1.20.0)\n\n\n## Samples\nCheck out the [sample repository](samples) for example code showing how the SDK can be used in the various scenarios:\n\n\n## Connecting\nCurrently only connection through Shared Access Keys is supported.\nYou can use both device keys or group keys.\n\n### Init\n```py\nfrom iotc import IoTCConnectType\nid_scope = 'scopeID'\ndevice_id = 'device_id'\nsasKey = 'masterKey' # or use device key directly\nconn_type=IoTCConnectType.SYMM_KEY # or use DEVICE_KEY if working with device keys\nclient = IoTCClient(id_scope, device_id, conn_type, sasKey)\n```\n\nYou can pass a logger instance to have your custom log implementation. (see [#Logging](#logging))\n\ne.g.\n\n```py\nfrom iotc import ConsoleLogger,IoTCLogLevel\nlogger = ConsoleLogger(IoTCLogLevel.ALL)\nclient = IoTCClient(id_scope, device_id, conn_type, sasKey, logger)\n```\n\n### Connect\n\n```py\nclient.connect()\n```\nAfter successfull connection, IOTC context is available for further commands.\n\n## Operations\n\n### Send telemetry\n\n```py\nclient.send_telemetry(payload,properties=None)\n```\n\ne.g. Send telemetry every 3 seconds\n```py\nwhile client.is_connected():\n    print('Sending telemetry')\n    client.send_telemetry({'temperature':randint(0,20),'pressure':randint(0,20),'acceleration':{'x':randint(0,20),'y':randint(0,20)}})\n    sleep(3)\n```\nAn optional *properties* object can be included in the send methods, to specify additional properties for the message (e.g. timestamp,etc... ).\nProperties can be custom or part of the reserved ones (see list [here](https://github.com/Azure/azure-iot-sdk-csharp/blob/master/iothub/device/src/MessageSystemPropertyNames.cs#L36)).\n\n\u003e **NOTE:** Payload content type and encoding are set by default to 'application/json' and 'utf-8'. Alternative values can be set using these functions:\u003cbr/\u003e\n_iotc.set_content_type(content_type)_ # .e.g 'text/plain'\n_iotc.set_content_encoding(content_encoding)_ # .e.g 'ascii'\n\n### Send property update\n```py\nclient.send_property({'fieldName':'fieldValue'})\n```\n\n## Listen to events\nDue to limitations of the Mqtt library for micropython, you must explictely declare your will to listen for incoming messages. This client implements a non-blocking way of receiving messages so if no messages are present, it will not wait for them and continue execution.\n\nTo make sure your client receives all messages just call _listen()_ function in your main loop. Be aware that some sleeping time (200 ms +) is needed in order to let the underlying library listen for messages and release the socket.\n\n```py\nwhile client.is_connected():\n    client.listen() # listen for incoming messages\n    client.send_telemetry(...)\n    sleep(3)\n```\nYou also need to subscribe to specific events to effectively process messages, otherwise client would just skip them (see below).\n\n### Listen to properties update\nSubscribe to properties update event before calling _connect()_:\n```py\nclient.on(IoTCEvents.PROPERTIES, callback)\n```\nTo provide property sync aknowledgement, the callback must return the \nproperty value if has been successfully applied or nothing.\n\ne.g.\n```py\ndef on_props(prop_name, prop_value):\n    if prop_value\u003e10:\n        # process property\n        return prop_value\n\nclient.on(IoTCEvents.PROPERTIES, on_props)\n```\n\n### Listen to commands\nSubscribe to command events before calling _connect()_:\n```py\nclient.on(IoTCEvents.COMMANDS, callback)\n```\nTo provide feedbacks for the command like execution result or progress, the client can call the **ack** function available in the callback.\n\nThe function accepts 2 arguments: the command instance and a custom response message.\n```py\ndef on_commands(command, ack):\n    print(command.name)\n    ack(command, 'Command received')\n\nclient.on(IoTCEvents.COMMANDS, on_commands)\n```\n\n## Logging\n\nThe default log prints to serial console operations status and errors.\nThis is the _API_ONLY_ logging level.\nThe function __set_log_level()__ can be used to change options or disable logs. It accepts a _IoTCLogLevel_ value among the following:\n\n-  IoTCLogLevel.DISABLED (log disabled)\n-  IoTCLogLevel.API_ONLY (information and errors, default)\n-  IoTCLogLevel.ALL (all messages, debug and underlying errors)\n\nThe device client also accepts an optional Logger instance to redirect logs to other targets than console.\nThe custom class must implement three methods:\n\n- info(message)\n- debug(message)\n- set_log_level(message);\n\n## One-touch device provisioning and approval\nA device can send custom data during provision process: if a device is aware of its IoT Central template Id, then it can be automatically provisioned.\n\n### How to set IoTC template ID in your device\nTemplate Id can be found in the device explorer page of IoTCentral\n![Img](assets/modelid_1.png)\n![Img](assets/modelid_2.png)\n\nThen call this method before connect():\n\n```py\nclient.set_model_id('\u003cmodelId\u003e');\n```\n\n### Manual approval (default)\nBy default device auto-approval in IoT Central is disabled, which means that administrator needs to approve the device registration to complete the provisioning process.\nThis can be done from explorer page after selecting the device\n![Img](assets/manual_approval.jpg)\n\n\n### Automatic approval\nTo change default behavior, administrator can enable device auto-approval from Device Connection page under the Administration section.\nWith automatic approval a device can be provisioned without any manual action and can start sending/receiving data after status changes to \"Provisioned\"\n\n![Img](assets/auto_approval.jpg)\n\n## License\nThis samples is licensed with the MIT license. For more information, see [LICENSE](./LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazure%2Fiot-central-micropython-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazure%2Fiot-central-micropython-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazure%2Fiot-central-micropython-client/lists"}