Pymodi 1.2.0

Description:

pymodi 1.2.0

Description

Python API for controlling modular electronics, MODI.

Promotion Video

Features
PyMODI provides a control of modular electronics, MODI

Platform agnostic control of modules through serial connection
Explicit CAN communication to MODI modules via magnetic connector
Utilities of wireless connection with BLE (Bluetooth Low Engery)
Update of MODI firmware consisting of both ESP32 and STM32 modules
Direct manipulation of MODI network module using MODI Play

Build Status

master
develop

System Support

System
3.6
3.7
3.8

Linux

Mac OS

Windows

Contribution Guidelines
We appreciate all contributions. If you are planning to report bugs, please do so here. Feel free to fork our repository to your local environment, and please send us feedback by filing an issue.
If you want to contribute to pymodi, be sure to review the contribution guidelines. This project adheres to pymodi's code of conduct. By participating, you are expected to uphold this code.

Installation

When installing PyMODI package, we highly recommend you to use Anaconda to manage the distribution.
With Anaconda, you can use an isolated virtual environment, solely for PyMODI.

[Optional] Once you install Anaconda, then:
# Install new python environment for PyMODI package, choose python version >= 3.6
conda create --name pymodi python=3.6

# After you properly install the python environment, activate it
conda activate pymodi

# Ensure that your python version is compatible with PyMODI
python --version

Install the latest PyMODI if you haven't installed it yet:
python -m pip install pymodi --user --upgrade

You can also install PyMODI at develop branch (containing latest changes but it can be unstable) with:
python -m pip install git+https://github.com/LUXROBO/pymodi.git@develop --user --upgrade

Alternatively, you can install a stable copy of PyMODI at a tag (representing a previous release) with:
python -m pip install git+https://github.com/LUXROBO/[email protected] --user --upgrade

Usage
Import modi package and create MODI object (we call it "bundle", a bundle of MODI modules).
# Import modi package
import modi

"""
Create MODI object, make sure that you have connected your network module
to your machine while other modules are attached to the network module
"""
bundle = modi.MODI()

[Optional] Specify how you would like to establish the connection between your machine and the network module.
# 1. Serial connection (via USB), it's the default connection method
bundle = modi.MODI(conn_type="ser")

# 2. CAN connection (via CAN shield, not recommended to use it directly)
bundle = modi.MODI(conn_type="can")

# 3. BLE (Bluetooth Low Energy) connection, it's wireless! But it can be slow :(
bundle = modi.MODI(conn_type="ble", network_uuid="YOUR_NETWORK_MODULE_UUID")

List and create connected modules' object.
# List connected modules
print(bundle.modules)

# List connected leds
print(bundle.leds)

# Pick the first led object from the bundle
led = bundle.leds[0]

Visualize how modules are connected.
# Print topology map without indicating module id
bundle.print_topology_map()

# Print topology map with module id printed
bundle.print_topology_map(print_id=True)

Let's blink the LED 5 times.
import time

for _ in range(5):
# turn on for 0.5 second
led.turn_on()
time.sleep(0.5)

# turn off for 0.5 second
led.turn_off()
time.sleep(0.5)

If you are still not sure how to use PyMODI, you can play PyMODI tutorial over REPL:
$ python -m modi --tutorial

As well as an interactive usage examples:
$ python -m modi --usage

Moreover, we provide api documentation, usage and creation examples, and a descriptive web page.
Additional Usage
To update MODI network module (the network module must be connected on serial),
$ python -m modi --update_network

To update MODI network module's base (as above, the network module must be connected on serial),
$ python -m modi --update_network_base

To update MODI modules (all modules but the network module),
$ python -m modi --update_modules

To diagnose MODI modules (helpful to find existing malfunctioning modules),
$ python -m modi --inspect

To debug MODI modules with PyMODI debugger,
$ python -m modi --debug

To check the performance of PyMODI on your machine,
$ python -m modi --performance

To initialize MODI modules implicitly (set i flag to enable REPL mode),
$ python -im modi --initialize

To see what other commands are available,
$ python -m modi --help

Sponsored by

History
0.1.0 (2018-06-28)

Release initial version of the package on in-house GitLab

0.1.1 (2018-07-20)

Fix requirements
Fix include path

0.1.2 (2018-07-23)

Python 3.4 support

0.2.0 (2018-07-25)

Implement Speaker module
Implement Display module

0.2.1 (2018-07-27)

Implement speaker module's tune() and off() methods
Remove duplicated codes

0.3.0 (2018-07-28)

Support python 2.7
Speed up the performance

0.3.1 (2018-07-28)

Fix requirements

0.4.0 (2018-08-20)

Improve performance
Complete first documentation

0.5.0 (2018-08-22)

Change the project name to pyMODI

0.5.1 (2018-11-07)

Fix "No MODI network module connected" issue

0.5.2 (2019-10-11)

Can control a pair of motors of the motor module by torque(), speed(),
angle()

0.6.0 (2019-10-18)

Improve performance

0.7.0 (2020-01-23)

Implement individual motor control
Implement set variable method in display
Implement test cases for each modi modules
Implement multiprocessing version of pymodi
Bug fixes

0.7.1 (2020-02-07)

Refactor file structures
Bug fixes

0.8.0 (2020-05-07)

Implement Can Message Handler
Implement Topology Manager
Improve connection reliability by separating communication functions
Bug fixes

0.9.0 (2020-07-07)

Implement Module Firmware Updater
Implement bluetooth connection via SPP
Implement MODI Priority Queue to increase response speed
Implement PyMODI tutor for teaching new-comers
Support multi MODI network modules given appropriate COM ports
Refactor getter/setter for each MODI module
Refactor motor module to use set_motor_channel internally
Update property values when setting properties
Add usage/creation example to the repository
Bug fixes

1.0.0 (2020-09-15)

Implement Network Firmware Updater
Implement BLE connection (excluding macOS support)
Implement MODI Play support via network module
Refactor module getter/setter interface
Enhance topology manager to work with battery module
Add functionality to reset existing user code on the modules
Bug fixes

1.0.1 (2020-10-06)

Implement experimental BLE functionality on Windows and macOS
Improve BLE connection stability in Linux Platform
Implement module usage manual (i.e. quick-start)
Implement module inspection functionality (i.e. diagnose)
Refactor GUI debugger design, fix initialization issue on macOS

1.1.0 (2020-12-17)

Implement GUI Firmware Updater in PyMODI
Implement network base (STM32) firmware updater
Implement GD32 firmware updater
Implement VirtualMODI integration code

1.2.0 (2022-02-16)

Detach GUI Firmware Updater from PyMODI to individual repo
Implement web client method for MODI json connection
Package PyMODI into a dockerfile via GHCR
Fix minor bug in BLE connection