# Mmdev: A JSR223 library for defining all your items and rules in Jython

**URL:** <https://community.openhab.org/t/mmdev-a-jsr223-library-for-defining-all-your-items-and-rules-in-jython/158151>\
**Category:** Scripts & Rules\
**Tags:** jsr223, rules, jython, items\
**Created:** [September 2, 2024, 7:06pm UTC](https://community.openhab.org/t/mmdev-a-jsr223-library-for-defining-all-your-items-and-rules-in-jython/158151 "2024-09-02T19:06:24Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![miningmarsh](https://community.openhab.org/letter_avatar_proxy/v4/letter/m/a88e57/32.png) [@miningmarsh](https://community.openhab.org/u/miningmarsh)\
**Post date:** [September 2, 2024, 7:06pm UTC](https://community.openhab.org/t/mmdev-a-jsr223-library-for-defining-all-your-items-and-rules-in-jython/158151/1 "2024-09-02T19:06:25Z")

</div>

# Preface

I’ve had a few people ask me at various times for a copy of my OpenHAB configuration. I’ve taken some time to clean up the code a bit, and I think I’m finally ready to release it.

This library contains an updated version of Ivan’s Helper Libraries. It will not function with the original library. I have tried to maintain backwards compatibility with the original library.

I haven’t maintained the unit tests, code typing, or documentation. I plan to begin work on those soon.

The rest of this post is a copy of the basic usage document for `mmdev` from [here](https://github.com/MiningMarsh/openhab-helper-libraries/blob/mmdev/mmdev.md). I will try to keep these in sync. This should be enough documentation to use the library for now, at least until the full code documentation is up to snuff.

# mmdev

`mmdev` is a community library for openhab’s jsr223 jython extension. It  
allows you to define your entire item and rule configuration in python, and is designed to have a simple to use interface. It generates and maintains the underlying items and rules automatically based on an object/event model that you define.

`mmdev` resembles an ORM to some extent. The primary goal of this library is to allow you to define behaviors between groups of items without having to use complex rule DSL logic. All logic is instead driven by standard python callback functions.

Here is a small example defining a fan that turns on when the weather temperature exceeds a certain value, but only while a power toggle is switched on. Additionally, the fan switch is exposed over google assistant via user-provided metadata:

```python2
from community.mmdev.device import as_device
from community.mmdev.manager import Manager

# Here we define the class definition for fan devices.
@as_device(ephemeral=True)
def Fan(device):
    
    # Define the properties/items driving this device class.
    energized = device.property(bool, 'Energized', default=False)
    monitor = device.property(bool, 'Monitor', default=False)
    powered = device.property(bool, 'Powered', default=False)
    setpoint = device.property(int, 'Setpoint', default=F
70, dimension='Temperature')

    # Here we define the behavior of this device, using property events.
    @monitor.on_change()
    @powered.on_change()
    def update():

        # This commands the item backing `energized`.
        energized.command = (

            # This retrieves the current value of the item backing `powered`,`monitor` and `setpoint` and translates them to native python typed values.
            powered.value and monitor.value > setpoint.value
        )

    # This declares the list of properties we want publicly exposed.
    return {
        energized,
        monitor,
        powered,
        setpoint
    }

# Create a device manager we can use to create device objects.
m = Manager()

# Create a free-floating temperature state property.
temperature = m.state_for(
    int, 'Temperature', default=70,
    channel='zwave:honeywell_th6320zw_00_000:controller:thermostat:sensor_temperature'
)

# Create a fan object, overriding the item for its monitor property and attaching the appropriate channel.
# Expose the energized channel over google assistant as a fan.
fan = m.device_for(
    device_class=Fan,
    device_name='Desk Fan',
    room_name='Study',
    energized_channel='tplinksmarthome:hs300:powerstrip_ac:outlet2#switch',
    monitor_proxy=temperature,
    energized_metadata={'ga': ('Fan', {
        "lang": "en",
        "roomHint" "Living Room",
        "name": "Living Room Fan"
    })}
)

# At this point, any time the temperature channel changes on the temperature state object, the fan device will toggle the outlet channel as needed.

```

## Installation

To install mmdev, download [this zip](https://github.com/MiningMarsh/openhab-helper-libraries/archive/refs/heads/mmdev.zip) and copy the automation folder to the root of your openhab configuration folder.

`mmdev` comes with an extended, maintained version of Ivan’s Helper Libraries. I have attempted to remain as backwards compatible as possible, but I may have missed something. If my version of the helper libraries breaks existing scripts, please let me know.

`mmdev` will not work with other versions of the helper libraries.

## Usage

Put user scripts in `automation/jsr223/lib/python/personal`.

Place extra community libraries in `automation/jython/lib/community`.

## Object Modelling

OpenHAB has native to it the concept of items, indivual values that can be tied  
to a channel. `mmdev` treats collections of these items as objects akin to real  
world devices. For example, a `fan` device might have a `power` and `speed` item  
associated with it that represents the power and speed of a real fan. `mmdev` refers to these objects as devices.

Devices are designed to allow you to declare a group of behaviors for a set of real world devices exactly once. You can then instantiate multiple devices using that declared behavior, generating items for each.

Devices are defined as python classes that describe the items they use and the  
rules they have between them. `mmdev` refers to its equivalent of items as  
device properties.

Devices have a room and a name associated with them. Two devices with the same  
type, name, and room should not be created, as this could lead to erratic  
behavior with the items backing the device properties.

### Devices

Devices are represented by objects in python. Publicly available properties are  
exposed as attributes on those objects.

A device property is used the same way both when defining a device class or  
accessing the fields on a device object. They can be used to change or query  
the state of an item or to create rules around that item.

### Collections

Devices have an associated collection name and class name. Collections are  
community modules defining a set of device classes that can be used with  
`mmdev`. `mmdev` has a number of objects it provides out of the box in a  
collection named `Builtin`.

The collection of a device can either be provided with the device definition, or it can be auto-detected.

Auto detection works as follows:

The grandparent of the current module is imported. If it imports successfully, and has a field ‘collection’ on it, that field is used. Otherwise, the name of the module is used as the collection. If the grandparent cannot be imported, it instead imports the parent and repeats the same process.

A device name is discovered based on the function name given during device definition.

### Properties

Properties wrap a single item each. Once a property is defined, `mmdev` will  
begin to maintain the item backing it transparently whenever a new device is instantiated..

#### Property Items

The underling item backing a property is auto-generated based on the `name`,  
`class_name`, `collection_name`, and `room_name` of a device.

You can query the item name of a property’s item using the `.item` attribute:

```python2
p = device.property(...)
LOGGER.info(p.item)

```

You can also query a device for the prefix it uses when generating items, or query a device for the item base name it would use for a property:

```python2
LOGGER.info(device.item_base)
LOGGER.info(device.property_item('property_name'))

```

#### Property Values and Types

Properties do not provide or accept raw OpenHAB typed values. Instead, `mmdev` translates openhab typed values to python typed values and vice-versa, transparently.

OpenHAB Types are directly translated to corresponding python types:  
- `DecimalType` values use the `int` type.  
- `OnOffType` values use the `bool` type.  
- `PercentType` values use the `float` type and should be a normalized value.  
- `HSBType` values use the `tuple` type, specifically a tuple of the form `(h, s, b)`.  
- `String` values use the `str` type.  
- `Group` values use the `set` type.  
- `Undefined` openhab values translate to `None`, and vice versa.

Numeric values can have a dimension added with the `dimension` parameter in the property constructor. An example dimension would be ‘Temperature’.

A unit can be assigned to a numeric type with the `unit` parameter in the property constructor. When a value is assigned, the corresponding QuanityType is sent instead.

The value of a property can be retrieved by inspecting it’s `.value` attribute. No caching is performed; every access will re-query openhab for the value and re-translate it.

### Property Mutation

The value of a property, like an item, can receive both a command and an update. By default, any updates or commands sent to a property are ignored if they are equivalent to the already set value. This can be specified either in the property constructor, or in individual command and update calls:

```auto
# declare a Num property.
p = device.property(int, 'Num', force=True)

# Num is commanded to 1
p.command = 1

# Num is updated to 2
p.update = 2

# Num is commanded to 2
p.command = 2

# Nothing happens
p.command(2, force=False)

```

### Property Rules

OpenHAB supports a rule engine based on item changes. Likewise, `mmdev` supports rules based on property value changes.

Every property exposes several decorator properties, which when used on a function or method, declares the appropriate underlying OpenHAB rules.

#### `property.on_change()`

Functions decorated with the `on_change` decorator will trigger any time the value of a property changes. If called without arguments, the callback will be called with no arguments. If passed the `pass_context=True` parameter, the callback will be called with the old value and new value passed as arguments. By default, `pass_context` will never pass None values to the callback function; you can override this with the `null_context=True` parameter.

```auto
p = device.property(int, 'Value', default=0)

@p.on_change(pass_context=True)
def log_changes(_, new):
    LOGGER.log('New Value: {}'.format(new))

```

#### `property.on_command()`

Functions decorated with the `on_command` decorator will trigger any time a property receives a command. If called without arguments, the callback will be called with no arguments. If the `pass_context=True` parameter is passed, the callback will be called with the commanded value passed as an argument. By default, `pass_context` will never pass None values to the callback function; you can override this with the `null_context=True` parameter.

```auto
p = device.property(int, 'Value', default=0)

@p.on_command(pass_context=True)
def log_command(command):
    LOGGER.log('New Command: {}'.format(command))

```

#### `property.on_update()`

Functions decorated with the `on_update` decorator will trigger any time a property receives an update. If called without arguments, the callback will be called with no arguments. If passed the `pass_context=True` parameter, the callback will be called with the commanded value passed as an argument. By default, `pass_context` will never pass None values to the callback function; you can override this with the `null_context=True` parameter.

```auto
p = device.property(int, 'Value', default=0)

@p.on_update(pass_context=True)
def log_update(update):
    LOGGER.log('New Update: {}'.format(update))

```

#### `property.on_activate`

Calls a callback whenever the value transitions to the value `True`.

```python2
p = device.property(int, 'Value', default=0)

@p.on_activate
def activated(update):
    LOGGER.log('Activated')

```

#### `property.on_deactivate`

Calls a callback whenever the value transitions to the value `False`.

```python2
p = device.property(int, 'Value', default=0)

@p.on_deactivate
def activated(update):
    LOGGER.log('Deactivated')

```

### The Rule Engine

`mmdev` has an underlying rule engine object it uses to declare its rules. The rule engine associated with a device is available on that device as the `rule_engine` attribute. This usually isn’t useful, but there is one decorator that is available from the rule engine that is very useful.

`device.rule_engine.loop` is a special decorator that registers a callback to execute once a minute. It also automatically distributes the timers across the time span of a minute, so that the rule load is a little more evenly distributed.

```auto
@device.rule_engine.loop
def log():
     LOGGER.info('Loop')

```

If you need a rule that is not available via the aforementioned methods, you can share any rule you like with a `rule` decorator bundled with `mmdev`. Rules decorated with this decorator will have the event object associated with the rule passed to them if they specify `pass_confext=True`.

```python2
from community.mmdev.rules import rule

@rule("cron '...')
def update():
    LOGGER.info('cron')

```

### Property Channels

Each property can have a single optional channel attached to it. This channel is declared when creating the property:

```python2
power = device.property(
    int, 'PortableACPower', default=0,
    channel='tplinksmarthome:hs300:powerstrip_ac:outlet2#power'
)

```

### Property Defaults

The items backing a property can be given a default value. This value is assigned to the property either the first time the item is created, or any time openhab boots while the property contains `None`. The default value is specified as part of the property constructor:

```python2
power = device.property(
    int, 'PortableACPower', default=0,
    channel='tplinksmarthome:hs300:powerstrip_ac:outlet2#power'
)

```

### Property Groups

Properties support having OpenHAB groups assigned to them during property construction via the `groups` parameter.

The value passed to this parameter _MUST BE_ a property object, not an item name:

```python2
g1 = device.group_for('TestGroup1')
g2 = device.group_for('TestGroup2')

device.property(
    groups={g1, g2},
    ...
)

```

### Property Proxying

When a property is instantiated, a proxy property can be provided alongside it. If a proxy property is provided, then no new item is created, and all property method calls on the new property will be redirected to call the proxy property’s methods. Metadata and groups will be actively merged with the existing metadata and groups on the proxied property.

```python2
test = device.property(int, 'Test', default=False)
proxy = device.property(int, 'Proxy', proxy=test)

# The underlying item for the Proxy property is never created.

```

## Groups

Groups are set type properties with no associated device.

Groups can be created either with either the device object’s, or device manager object’s, `group_for` method. Both accept a metadata parameter for the group’s metadata.

```python2
m = Manager()
g = m.group_for('Test', metadata={})

```

```python2
g = device.group_for('Test', metadata={})

```

## State Properties

State properties are properties unbound from a device, and can be created with a device manager’s `state_for` method. It accepts all the same parameters as a device property.

```python2
m = Manager()
sleeping = m.state_for(bool, 'Sleeping', default=False)

```

## Ephemeral Devices

Special ephemeral device objects can be created with the device manager’s `ephemeral_for` method. It requires a room and device name, and returns a special device object. This device object has an overridden `property` method on it that, in addition to creating a property, also exposes it as an attribute on the device object. The name of the attribute is determined by converting it from `CamelCase` to `camel_case`, where spaces are stripped before conversion.

```python2
m = Manager()
dev = m.ephemeral_for('Living Room', 'Test')
test = dev.property(bool, 'Test', default=False)

@dev.test.on_change()
def test_change():
    LOGGER.error(test.value)

```

## Defining a Device Class

Device classes are very simple:  
The class object can have an optional `collection` and `name` attribute defining the device class collection and device class name. If not defined, the collection and name will be inferred from the module path of the device, and the device class name, respectively.

All device classes must have an **init** function that accepts a single parameter `device` (in addition to self) and any number of keyword parameters. Keyword parameters can be provided to the device manager when creating an instance of the device.

### Using the `@as_device` helper

Instead of creating a device class directly, it is recommended that you use the `@as_device` decorator from `community.mmdev.device` when defining device classes. This decorator optionally accepts both a specific collection and device name, which are otherwise inferred.

The decorator takes a function with a singular parameter `device` and any number of keyword arguments. The keyword arguments can be provided when instantiating the device with a device manager.

The function is called when the device is created. It is passed a device object that the function can define properties on, and define behaviors around. Finally, the function returns a set of properties it wants exposed publicly, or the empty set of the entire device is private.

The device object also allows the function to create groups specific to the device with the `group_for` method, and allows access to a rule engine if needed through it’s `rule_engine` attribute.

Finally, if you pass it the `ephermeral=True` parameter, it will generate a random collection and name to avoid clashing with any other existing device classes. This is useful when used in your startup scripts.

Here is an example defining a Lock class which locks itself if it has been unlocked for longer than a specified time (60 seconds by default):

```auto
from time import time
from community.mmdev.device import as_device

@as_device(collection='Example')
def Lock(device, timeout=60):

    locked = device.property(bool, 'Locked', default=False)
    last_transition = device.property(int, 'LastTransition', default=0)

    @locked.on_change()
    def transition():
        last_transition.command = time()

    @device.rule_engine.loop
    def check_lock():
        if time() - last_transition.value < timeout:
            return

        if locked.value:
            return

        locked.command = True

    return {
        locked
    }

from community.mmdev.manager import Manager

m = Manager()

lock = m.device_for(
    device_class=Lock,
    room_name='Hallway',
    device_name='Lock',
    timeout=300
)

```

The property set returned from the function does two things:

- It exposes the properties as attributes on the resulting device object. The attribute names are based on the property names after translation from `CamelCase` to `camel_case` while ignoring spaces.
- It exposes a number of keyword arguments to influence the created properties.

The keyword arguments take the following form, where `prop` is the property name of the created property:

- `{prop}_channel`
- `{prop}_groups`
- `{prop}_metadata`
- `{prop}_default`
- `{prop}_proxy`
- `{prop}_normalize`

These keyword arguments will pass themselves to the underlying property’s constructor when the function creates it. This is only done for returned properties, all other properties can be seen as “private properties”.

```python2
lock = m.device_for(
    room_name='Hallway',
    device_name='Lock',
    locked_channel='mqtt:topic:locked:hallway'
)

```

This is the primary reason using `@as_device` is recommended: The extra keyword arguments gives you an easy way to assign channels and groups to devices as needed.

## Garbage Collection

Item creation and garbage collection works in the following way:

All items created by properties have a heartbeat in their metadata. A cron job updates it once a minute for each live item that `mmdev` knows about.

A garbage collection daemon checks once a minute, and deletes any items that have a heartbeat older than 5 minutes.

When items are created, `mmdev` will delay itself for a couple minutes to allow the item to appear and get initialized. Only after this wait will it create items. This means a fresh boot might take a few minutes before you see object behavior working. This is fine so that persistent items have time to restore their value before you use them.

This method of garbage collection was chosen as it allows items from multiple user scripts to co-exist easily, and with a lack of any available IPC mechanisms.

All `mmdev` items begin with `MMDEV_`, and the garbage collector will ignore any item that doesn’t follow that pattern.

## Example User Script

Since all my security tokens exist in things configuration, I currently keep a copy of the script that controls my apartment [here](https://github.com/MiningMarsh/openhab-helper-libraries/blob/mmdev/automation/jython/lib/community/mmdev/example.py).

---

<div class="post-metadata">

**Author:** ![EstroVi](https://community.openhab.org/user_avatar/community.openhab.org/estrovi/32/111385_2.png) [@EstroVi](https://community.openhab.org/u/EstroVi)\
**Post date:** [September 10, 2024, 4:42pm UTC](https://community.openhab.org/t/mmdev-a-jsr223-library-for-defining-all-your-items-and-rules-in-jython/158151/2 "2024-09-10T16:42:36Z")

</div>

Thank you so much for posting, omfg
