Mydin-classes-diagram

Page(s) en cours de traduction/élaboration. Page(s) under translation/construction

About this section

Before reading the classes documentation, it may be opportune to understand how the MyDin core is designed.

That will help to understand how the code works and where are located the key items when programming your MyDin project with MicroPython.

Class diagram

Here a short description of the main classes and their responsibilities:

• DinControler : Base class responsible for starting the asynchronous execution. It puts every mechanism in place to initiate the setup then start asynchronous tasks including the user_loop task. A this level, the DinCOntroler doesn't know anything about the underlaying microcontroler used. DinControler also takes care of the process termination.
• PicoControler : Base class for myDin solution based on Raspberry-Pi Pico microcontroler. PicoControler inherits of DinControler (and all its behavior). At the PicoContoler level, we can create object related to microcontroler hardware that will be shared accross all the descendant classes. At the PicoControler level we can define the common I2C bus, RTC clock, internal temperature sensor, watchdog and e.
• Pico3Mod : Specialized implementation of the PicoControler for a 3 modules size DIN. As the microcontroler is now placed on a PCB with fixed dimensions and obvious placement constraints (due to the 3 modules Din) then the specific hardware design like buttons, LEDs, interface connectors can be defined by this class. This class also defines the interface between the controler and the 3 modules backplane.
• Pico6Mod : Another specialized implementation of the PicoControler for a 6 modules size DIN. Thanks to additional place available, it is also possible to add a LCD/OLED display, mini-joystick aside the usual interface.
• TwoRelay3Mod is a specialized Backplane implementation for a 3 modules DIN. Backplane 3 modules shares a common interface with the 3 modules Controler (Pico3Mod and any 3 modules Controler will use exactly the same interface).

Backplane class must implements the attach( controler ) method.
The attach( controler ) method is called by configure() to expose the backplane properties into the controler object.

DinControler

Header

Ancestor None

Class DinControler

Module controler

DIN Size Any size

Descr Base class responsible for starting the asynchronous execution. It puts every mechanism in place to initiate the setup then start asynchronous tasks including the userloop task. A this level, the DinControler doesn't know anything about the underlaying microcontroler used. DinControler also takes care of the process termination.

Details about DinControler class are available at "asynchronous tasks" details. Here is the process behind the run() method.

Attributes

backplane : object

Reference to the backplane instance created by the configure() function. The backplane is an instance of type BackplaneClass.

is_async : boolean

True when the DinControler is running asyncio code otherwise, the DinControler is running "procedural" code.

This property is set to True by the run() method.

loop_exception : object

If an exception is raised by the userloop during asynchronous execution then the run() exits and loop_exception contains a reference to the catched exception.

When the userloop exits for another reason (eg: APP_RUN=STOP) then the loop_exception should still be None.

Remark: loop_exception is set to None when run() starts.

loop_time_ms : int

Being configured to 20 milliseconds, this async.sleep_ms() time is inserted after each userloop iteration. It allows other tasks to get execution time.

The value of loop_time_ms can be ajusted to provide more time to other tasks.

Methods

__init__()

Constructor of the DinControler class. This constructor is not called directly, the DinControler class is used as a based call for a given MCU category class (RP2040, ESP32, ...).

def __init__( self, BackplaneClass, RunApp_pin ):

• BackplaneClass : Class of the backplane to be associated with the controler (eg: TwoRelay3Mod).
• RunApp_pin : identification of the input pin to be used as RUN_APP swich. It will be configured with Internal Pullup. Software will not start (or will stop) when the pin is tied to ground.

setup()

Setup the userloop and other key parameter for an asynchronous code execution with run(). The userloop is the main user code repetitively executed by the asynchronous execution.

def setup( self, setup=None, loop=None, on_tasks_create=None ):

• setup : function setting-up the hardware of your DIN project. Called function receives din object is as parameter.
• loop : async function executing the userloop code. The din object is received as parameter. Called function receives the din object as parameter.
• on_task_create : callback event allowing the user code to insert its own project tasks.

The example here below shows how to create the userloop and the setup function.

from mydin import configure
from mydin.pico import Pico3Mod
from mydin.backplane.relays import TwoRelay3Mod 
import time, sys

from serlcd import SerLCD

# Which Controler + Backplane to use
din = configure( Pico3Mod, TwoRelay3Mod )

def setup( din ):
  # Add a new attribute to "din" instance
  din.lcd = SerLCD( din.i2c, cols=16, rows=4 )
  din.lcd.backlight( (0,0,255) ) # Blue
  din.lcd.set_cursor( (7,1) ) # column,line (0 à N-1)
  din.lcd.print( "MyDin" )
  din.lcd.set_cursor( (3,2) ) # column,line (0 à N-1)
  din.lcd.print( "by MCHobby.be")
  din.lcd_last_update = time.ticks_ms()

async def loop( din ):
  """ called again and again (like Arduino) """

  # Update LCD once every 5 seconds
  if time.ticks_diff( time.ticks_ms(), din.lcd_last_update )>5000:
    din.lcd.clear()
    din.lcd.print("Internal Temp:" )
    din.lcd.set_cursor( (3,1) )
    din.lcd.print( "%2.2f C" % din.internal_temperature )
    din.lcd_last_update = time.ticks_ms()


din.setup( setup=setup, loop=loop )
din.run()

Example with tasks creation is available on the micropython-mydin repository.

setup_watchdog()

Abstract method that must be overrided in descendant class

The setup_watchdog() method activates the hardware Watchdog of the microcontroler. 2 seconds (2000 ms) may represent a good timing.

Once activated, the feed_watchdog() must be called before the timeout occurs otherwise the microcontroler will reset.

Remarks:

• the watchdog is automatically feeded at every iteration of the userloop.
• do not block the userloop execution because it may timeout the watchdog
• take care of the timing when using blocking function (like Ethernet request) because it may timeout the watchdog.

def setup_watchdog( self, time_ms ):

• time_ms : timeout of the watchdog before resetting occurs.

feed_watchdog()

Abstract method that must be overrided in descendant class

The feed_watchdog() method just reset the watchdog timeout.

Remarks:

• the feed_watchdog() is automatically called every iteration of the userloop.

def feed_watchdog( self ):

task_setup()

Overridable method

This method setup the userloop then calls the on_task_create event (when provided to the setup() method.

That method is usually overrided in descendant class to append Controler specific tasks (eg: the PicoControler append monitoring and ds18b20 tasks).

def tasks_setup( self, async_evloop ):

before_run()

Overridable method

This method is called before starting the userloop. The execution is aborted when the before_run() returns False.

Overriding it allows the descendant class to checks specific condition before allowing the user code to run (EG: Pico3Mod checks the internal temperature before allowing the userloop to starts).

def before_run( self ):

after_run()

Overridable method

This method is called when the userloop ends for any reason (RUN_APP or userloop exception).

No return value is expected from this method.

def after_run( self ):

run()

Start the execution of the userloop execution. See the

def run( self ):