{"id":14963436,"url":"https://github.com/datavenueliveobjects/liveobjects_sdk_for_python","last_synced_at":"2025-10-25T02:30:37.499Z","repository":{"id":40486542,"uuid":"304311225","full_name":"DatavenueLiveObjects/LiveObjects_SDK_for_Python","owner":"DatavenueLiveObjects","description":"Live Objects SDK for Python \u0026 MicroPython","archived":false,"fork":false,"pushed_at":"2023-03-12T11:35:55.000Z","size":804,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-31T04:51:37.190Z","etag":null,"topics":["esp32","esp8266","iot","linux","liveobjects","micro-python","micropython","mqtt","mqtts","orange","python","raspberry","raspberry-pi","raspberrypi","windows"],"latest_commit_sha":null,"homepage":"https://liveobjects.orange-business.com","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/DatavenueLiveObjects.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-15T11:57:10.000Z","updated_at":"2022-11-28T08:48:47.000Z","dependencies_parsed_at":"2024-09-13T19:15:53.465Z","dependency_job_id":null,"html_url":"https://github.com/DatavenueLiveObjects/LiveObjects_SDK_for_Python","commit_stats":{"total_commits":87,"total_committers":5,"mean_commits":17.4,"dds":0.2068965517241379,"last_synced_commit":"33edd0010779ff7757cf698ca061cb28072eca73"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DatavenueLiveObjects%2FLiveObjects_SDK_for_Python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DatavenueLiveObjects%2FLiveObjects_SDK_for_Python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DatavenueLiveObjects%2FLiveObjects_SDK_for_Python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DatavenueLiveObjects%2FLiveObjects_SDK_for_Python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DatavenueLiveObjects","download_url":"https://codeload.github.com/DatavenueLiveObjects/LiveObjects_SDK_for_Python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238059129,"owners_count":19409601,"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":["esp32","esp8266","iot","linux","liveobjects","micro-python","micropython","mqtt","mqtts","orange","python","raspberry","raspberry-pi","raspberrypi","windows"],"created_at":"2024-09-24T13:31:30.298Z","updated_at":"2025-10-25T02:30:37.102Z","avatar_url":"https://github.com/DatavenueLiveObjects.png","language":"Python","readme":"# Prototype with Orange using Live Objects\n### Discover Orange  [**Live Objects**](https://liveobjects.orange-business.com) using dedicated SDK for **Python 3 and uPython compatible** boards and systems.\n\nThis code wraps all the functions necessary to make your object work with Live Objects.\n\nYou can declare parameters, which you can later update OTA from Live objects. You can also create commands to trigger actions remotely.\nOnly thing you must do yourself is connecting the board with internet.\n\nCode uses MQTT connection to exchange data with Live objects under the hood to keep your parameters up to date or execute the commands received without you having to take care of them (apart from writing the code of these commands, of course).\n\n## Compatibility ##\n| System        | MQTT | MQTTS |\n|:--------------|:----:|:-----:|\n| Linux         |  OK  |  OK   |\n| Windows       |  OK  |  OK   |\n| Raspberry Pi  |  OK  |  OK   |\n| ESP8266       |  OK  |   -   |\n| ESP32         |  OK  |  OK   |\n| LoPy (Pycom)  |  OK  |   -   |\n| GPy (Pycom)   |  OK  |   -   |\n\n## Prerequisites / dependencies ##\nThis code needs a few libraries to run:\n- Python needs [paho-mqtt](https://pypi.org/project/paho-mqtt/)\n    - Python for Windows needs [python-certifi-win32](https://pypi.org/project/python-certifi-win32/)\n- uPython needs [umqttsimple](https://github.com/micropython/micropython-lib/blob/master/micropython/umqtt.simple/umqtt/simple.py) and [umqttrobust](https://github.com/micropython/micropython-lib/blob/master/micropython/umqtt.robust/umqtt/robust.py)\n\n## How to use ##\n\n1. Log in to [Live Objects](https://liveobjects.orange-business.com) or request a [trial account](https://liveobjects.orange-business.com/#/request_account) (up to 10 devices for 1 year) if you don't have one,\n2. Create an [API key](https://liveobjects.orange-business.com/#/administration/apikeys) for your device. Give it a name, select the *Device access* role and validate. Copy the key,\n3. Clone or download the directory from GitHub,\n4. Change **\\\u003cAPIKEY\\\u003e** in `credentials.py` to one you generated,\n5. Run selected `.py` script\n\n## Developer guide ##\n\n### Constructor ###\n\nConstructor of LiveObjects looks like below:\n\n```Python\nlo = LiveObjects.Connection()\n```\n\n### Debug messages ###\n\nYou can use LiveObjects to output debug messages.\n\n```Python\nVALUE = 21\n# INFO / ERROR / WARNING\nlo.output_debug(LiveObjects.INFO, \"example value\", VALUE, ...)\n# Output: [INFO] example value 21 ...\n```\n\n### Declare parameters ###\nYou can update over the air some parameters of your script using Live Objects's parameters. Parameters and Commands must be declared **before** your device connects to Live Objects.\n\nYou can declare parameters with the `addParameter()` instruction, which accepts the following arguments:\n- the label of your parameter as it will be displayed on Live Objects;\n- the value of parameter\n- parameter type [INT STRING FLOAT BINARY]\n- (optional) a callback function, if you need to perform some tasks after the parameter has been updated\n\nTo retrieve a parameter use function `getParameter()` which takes following arguments:\n- Parameter name\n\nExample:\n\n```Python\nlo.add_parameter(\"message_rate\", 25, LiveObjects.INT)\nlo.add_parameter(\"send_DHT_data\", true, LiveObjects.BINARY, my_callback_function)\n# ...\nif lo.get_parameter(\"send_DHT_data\"):\n    lo.add_to_payload(\"temperature\", DHT.read_temeprature())\n    lo.add_to_payload(\"humidity\", DHT.read_humidity())\n```\n\nThe callback function takes 2 arguments:\n```Python\ndef my_callback_function(parameter_name, new_value):\n    # do stuff\n```\n\nFurther reading on Live Objects' [Parameters](https://liveobjects.orange-business.com/doc/html/lo_manual.html#_configuration).\n\n### Declare commands ###\nCommands let you trigger specific actions on your device from Live Objects. Parameters and Commands must be declared _before_ your device connects to Live Objects.\n\nCommands can be declared using the `addcommand()` instruction, which accepts the following arguments:\n- the label of your command\n- the callback function that will execute the command.\n\n```Python\nlo.add_parameter(\"a command\", my_callback, );\n```\n\nThe callback function should take 1 parameter and return dictionary:\n```Python\ndef my_callback(args={}):\n    # do stuff\n    return {}\n```\n\nArguments and response are optional when using commands, but they can be useful if you want to pass parameters to your function. For instance, you could define a `play tone` command that will use some parameters like the frequency of the tone, or its duration.\n- Any incoming arguments will be passed as member of a dictionary\n- You can pass response arguments in the form of a dictionary by returning them\n\n```Python\ndef play_tone(args={}):\n    duration = args[\"duration\"]\n    frequency = args[\"frequency\"]\n    # play the tone accordingly to arguments\n    # ...\n    return {\"I played\": \"the tone\"}\n\n\ndef setup():\n    lo.add_command(\"play tone\", play_tone)\n```\n\u003e Warning: **Command name and arguments are case-sensitive when creating the command on Live Objects.**: On the opposite, there is no specific order for specifying the command arguments.\n\nFurther reading on Live Objects' [Commands](https://liveobjects.orange-business.com/doc/html/lo_manual.html#MQTT_DEV_CMD).\n\n### Sending data ###\nYou can send data very easily to Live Objects.\n\n#### Dead simple method ####\nCompose your payload using the `addToPayload()` instruction. You will need to provide a label for your value, and the data itself. Your data can be of any simple type.\n\nData is added on each call to `addToPayload()`, so repeat the instruction if you have multiple data to send. When your payload is ready, send it using `sendData()`. That simple.\n\n```Python\nVALUE = 21\nMY_OTHER_VALUE = 37\n\n\ndef foo():\n    # collect data\n    lo.add_to_payload(\"my data\", VALUE)\n    lo.add_to_payload(\"my other data\", MY_OTHER_VALUE)\n    lo.send_data()  # send to LiveObjects\n```\n\nAs soon the data is sent, your payload is cleared and waiting for the next sending.\n\n### Advanced payload features ###\n\n```Python\n# Add \"model\" property to your message\nlo.add_model(\"example_name\")\n\n# Add \"tag\" property to your message\nlo.add_tag(\"kitchen\")\nlo.add_tags([\"humidity\", \"bathroom\"])\n\n# Use your object as payload (this function doesn't append current payload)\nobj = {\"example\": \"value\", \"example2\": \"value2\"}\nlo.set_object_as_payload(obj)\n```\n\n\n### Connect, disconnect and loop ###\nYou can control the connection and disconnection of your device using `connect()` and `disconnect()`.\n\n\nIn order to check for any incoming configuration update or command, you need to keep the `loop()` instruction in your main loop.\n```Python\ndef foo():\n    lo.connect();\n    while True:\n        # Do some stuff\n        #...\n        lo.loop(); #Keep this in main loop\n    lo.disconnect()\n```\n\n### Changing default carrier to connect to the network ###\n\nEvery board has its own default carrier for connection to the network (see below). \n\n| System        | Default carrier | Optional carrier |\n|:--------------|:---------------:|:----------------:|\n| Linux         | Delivered by OS |        -         |\n| Windows       | Delivered by OS |        -         |\n| Raspberry Pi  | Delivered by OS |        -         |\n| ESP8266       |      Wi-Fi      |        -         |\n| ESP32         |      Wi-Fi      |        -         |\n| LoPy (Pycom)  |      Wi-Fi      |        -         |\n| GPy (Pycom)   |      Wi-Fi      |       LTE        |\n\nFor GPy you can switch connectivity to optional carrier. You need to do change in `Connection` class in `Connection.py`\nfrom:\n```Python\ndef __init__(self, debug=True):\n    self.__board = LiveObjects.BoardsFactory(net_type=LiveObjects.BoardsInterface.DEFAULT_CARRIER)\n...\n```\nto:\n```Python\ndef __init__(self, debug=True):\n    self.__board = LiveObjects.BoardsFactory(net_type=LiveObjects.BoardsInterface.LTE)\n...\n```\nThen GPy will connect via LTE network.\n\n### Adding new boards ###\n\nThere is possibility to add your new type of board supporting Python/uPython. \nYou need to add your own class in `hal.py`. Name of this class has to be the same as output of `sys.platform`\nand has to start from capital letter.\n```commandline\n\u003e\u003e\u003e sys.platform\n'GPy'\n\u003e\u003e\u003e \n```\nBelow code shows basic constructor:\n```Python\ndef __init__(self, net_type):\n    self._lang_id = BoardsInterface.MICROPYTHON\n    self._net_type = BoardsInterface.WIFI if net_type == BoardsInterface.DEFAULT_CARRIER else net_type\n    self._carrier_capability = (BoardsInterface.WIFI,)\n    self._wifi_tls_capability = False\n    self._credentials = super().create_credentials(self._net_type)\n```\nBasic fields meaning:\n- **_lang_id**: used Python dialect: PYTHON / MICROPYTHON,\n- **_net_type**: used type of network: WIFI / LTE / network delivered by OS / ...\n- **_carrier_capability**: _tuple_ containing supported type(s) of network,\n- **_wifi_tls_capability**: _True_ if TLS is supported and MQTTS could be used, \n- **_credentials**: required credentials depended on network type: SSID/PASS for Wi-Fi, PIN/APN for LTE etc. \n\nIf other specific fields are necessary you need to define them.\nYou need to override specific methods - e.g. `connect` which is depended on type of board. \nAll specific functions are placed in `services.py`. \nIf your board needs function supporting its equipment you need to put it in this file.   \n\n## VL6180X Sensor use-case ##\n\nWe can connect sensor using I\u003csup\u003e2\u003c/sup\u003eC to board supporting Python like **Raspberry Pi**. \n\nThe [VL6180X](https://www.st.com/en/imaging-and-photonics-solutions/vl6180x.html) is the latest product based on ST’s patented FlightSense™technology. \nThis is a ground-breaking technology allowing absolute distance to be measured independent of target reflectance. \nInstead of estimating the distance by measuring the amount of light reflected back from the object (which is significantly influenced by color and surface), \nthe VL6180X precisely measures the time the light takes to travel to the nearest object and reflect back to the sensor (Time-of-Flight).\nDescription from st.com.\n\n### Prerequisites ###\n\n#### Enabling I\u003csup\u003e2\u003c/sup\u003eC ####\nEnable (if needed) **I\u003csup\u003e2\u003c/sup\u003eC** interface on your Raspberry Pi using terminal and command:\n```bash\nsudo raspi-config\n```\nand selecting: **3 Interface Options** -\u003e **P5 I2C** -\u003e **\\\u003cYes\\\u003e**\n\n![I2C_Enabling](image/enable_I2C.png)\n\n#### Wiring ####\n![Wiring](https://www.raspberrypi-spy.co.uk/wp-content/uploads/2012/06/Raspberry-Pi-GPIO-Header-with-Photo-768x512.png \"Mapping\")\n\n\u003cbr\u003e\n\nExample of development module using VL6180X you can find [here](https://kamami.pl/en/kamod-kamami-peripheral-modules/559362-kamodvl6180x-a-module-with-distance-gesture-and-als-sensor.html). Below diagram shows how to connect it to Raspberry Pi.\n\n![Schematics](image/RPi_VL6180X.png \"Schematics\")\n\n#### Adding VL6180X Python module ####\nNecessary module by [Adafruit](https://learn.adafruit.com/adafruit-vl6180x-time-of-flight-micro-lidar-distance-sensor-breakout/python-circuitpython) can be installed using `pip` \n```bash\npip3 install adafruit-circuitpython-vl6180x\n```\n\n#### How to use ####\nTo run you need to use below command:\n```bash\npython3 7_distance_and_light_sensor.py\n```\n\n---\n\n# Installation guide for uPython #\n## Example for ESP32 / ESP8266 ##\n### Requirements ###\n1. [ampy](https://learn.adafruit.com/micropython-basics-load-files-and-run-code/install-ampy)\n2. [umqttsimple, umqttrobust and ssl](https://github.com/micropython/micropython-lib) (for your convenience they are included in `micropython` folder)\n3. [PuTTY](https://www.putty.org/) (for Windows)\n\n### Installation steps ###\n\n1. Preparation \n\nChange **\\\u003cAPIKEY\\\u003e** in `credentials.py` to one you generated.\\\nChange **\\\u003cWIFI_SSID\\\u003e** and **\\\u003cWIFI_PASS\\\u003e** suitable to your Wi-Fi or \nchange **\\\u003cPIN\\\u003e** and **\\\u003cAPN\\\u003e** suitable to your SIM card.\n\n2. Copy files into device\n```commandline\n\u003e ampy --port COMx put umqttrobust.py \n\u003e ampy --port COMx put simple.py   \n\u003e ampy --port COMx put LiveObjects // It will copy directory with its content \n```\n3. Prepare your script and save it as `main.py` then copy file into device. \nYou can use one of example ones (`1_send_data.py`, ...) renaming it to `main.py` \n```Shell\n\u003e ampy --port COMx put main.py\n```\n\n\n4. Connect to device and check if it's working using PuTTY\n    \n    Ctrl + D soft resets device\n\n    Ctrl + C Stops currently running script\n\n### Summary ###\n\nAfter all steps content of the device should look like below:\n```commandline\n\u003e ampy --port COMx ls\n/LiveObjects\n/boot.py\n/main.py\n/umqttrobust.py\n/simple.py\n\n\u003e ampy --port COMx ls LiveObjects\n/LiveObjects/Connection.py\n/LiveObjects/__init__.py\n/LiveObjects/hal.py\n/LiveObjects/credentials.py\n/LiveObjects/services.py\n```\nwhere COMx means port on your computer (e.g. COM8) with connected microPython board. \n\n## Example for LoPy / GPy ##\n\nYou can do the steps as above but better is to use [Pymakr plug-in](https://pycom.io/products/supported-networks/pymakr/) for **Visual Studio Code** or **Atom** delivered by [Pycom](https://pycom.io/). \nPlug-in supports code development, its upload to the board and communication with board. \n\n## VL6180X Sensor use-case ##\n\nSensor described in this [section](#vl6180x-sensor-use-case) can be used on boards supporting microPython.\n\n### Prerequisites ###\n\n#### Wiring ####\nYou need to connect I\u003csup\u003e2\u003c/sup\u003eC interface (SCL \u0026 SDA) and power lines on the board with corresponding pins on the sensor.\nYou need to be aware that **boards can use different GPIOs for I\u003csup\u003e2\u003c/sup\u003eC** purposes. Set of typical pairs is placed \nin function `get_i2c()` in file `hal.py`. If your board uses other GPIO pins, you need to add them to the tuple `typical_gpio`. \n```Python\ndef get_i2c():\n    import machine\n    typical_gpio = ([22, 23], [5, 4], [22, 21])\n...\n```\n![ESP32_sch](image/ESP32_VL6180X_sch.png)\n\nExample of wiring ESP32 board with GPIO22 and GPIO21 (_source: https://randomnerdtutorials.com/esp32-pinout-reference-gpios/_)\n\n![ESP32](image/ESP32_VL6180X.jpg)\n\n#### How to use ####\n1. You need to upload additional library for VL6180X support (it is placed in `micropython` folder):\n```commandline\n\u003e ampy --port COMx put vl6180x_micro.py\n``` \n2. Copy `7_distance_and_light_sensor.py` as `main.py` and upload it into board. \n\nAfter above operations you can see:\n```commandline\n\u003e ampy --port COMx ls\n/LiveObjects\n/boot.py\n/main.py\n/umqttrobust.py\n/simple.py\n/vl6180x_micro.py\n\n\u003e ampy --port COMx ls LiveObjects\n/LiveObjects/Connection.py\n/LiveObjects/__init__.py\n/LiveObjects/hal.py\n/LiveObjects/credentials.py\n/LiveObjects/services.py\n```\n3. Connect to device and check if it's working using PuTTY.\n\n\n## Troubleshooting ##\nIf you are getting 'MQTT exception: 5' check your api key\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatavenueliveobjects%2Fliveobjects_sdk_for_python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatavenueliveobjects%2Fliveobjects_sdk_for_python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatavenueliveobjects%2Fliveobjects_sdk_for_python/lists"}