core.utils

This module provides miscellaneous utility functions that are used across the core packages and modules.

core.utils.kw(dict, value)

In a given dictionary, get the first key that has a value matching the one provided.

Parameters

  • dict (dict) – the dictionary to search

  • value (str) – the value to match to a key

Returns

string representing the first key with a matching vlaue, or

None if the value is not found

Return type

str or None

core.utils.iround(x)

Round a float to the nearest integer.

Parameters

x (float) – the float to round

Returns

integer value of float

Return type

integer

core.utils.getItemValue(item_or_item_name, defVal)

Returns the Item’s value if the Item exists and is initialized, otherwise returns the default value. itemRegistry.getItem will return an object for uninitialized items, but it has less methods. itemRegistry.getItem will throw an ItemNotFoundException if the Item is not in the registry.

Parameters

  • item_or_item_name (Item or str) – name of the Item

  • defVal (int, float, ON, OFF, OPEN, CLOSED, str, DateTime) – the default value

Returns

the state if

the Item converted to the type of default value, or the default value if the Item’s state is NULL or UNDEF

Return type

int, float, ON, OFF, OPEN, CLOSED, str, DateTime, or None

core.utils.getLastUpdate(item_or_item_name)

Returns the Item’s last update datetime as an ‘org.joda.time.DateTime <http://joda-time.sourceforge.net/apidocs/org/joda/time/DateTime.html>`_.

Parameters

item_or_item_name (Item or str) – name of the Item

Returns

DateTime representing the time of the Item’s last update

Return type

DateTime

core.utils.sendCommand(item_or_item_name, new_value)

Sends a command to an item regardless of its current state.

Parameters

  • item_or_item_name (Item or str) – name of the Item

  • new_value (Command) – Command to send to the Item

core.utils.postUpdate(item_or_item_name, new_value)

Posts an update to an item regardless of its current state.

Parameters

  • item_name (Item or str) – Item or name of the Item

  • new_value (State) – state to update the Item with

core.utils.post_update_if_different(item_or_item_name, new_value, sendACommand=False, floatPrecision=None)

Checks if the current state of the item is different than the desired new state. If the target state is the same, no update is posted.

sendCommand vs postUpdate: If you want to tell something to change (turn a light on, change the thermostat to a new temperature, start raising the blinds, etc.), then you want to send a command to an Item using sendCommand. If your Items’ states are not being updated by a binding, the autoupdate feature or something else external, you will probably want to update the state in a rule using postUpdate.

Unfortunately, most decimal fractions cannot be represented exactly as binary fractions. A consequence is that, in general, the decimal floating-point numbers you enter are only approximated by the binary floating-point numbers actually stored in the machine. Therefore, comparing the stored value with the new value will most likely always result in a difference. You can supply the named argument floatPrecision to round the value before comparing.

Parameters

  • item_or_item_name (Item or str) – name of the Item

  • new_value (State or Command) – state to update the Item with, or Command if using sendACommand (must be of a type supported by the Item)

  • sendACommand (Boolean) – (optional) True to send a command instead of an update

  • floatPrecision (int) – (optional) the precision of the Item’s state to use when comparing values

Returns

True, if the command or update was sent, else False

Return type

bool

core.utils.postUpdateCheckFirst(item_or_item_name, new_value, sendACommand=False, floatPrecision=None)

Checks if the current state of the item is different than the desired new state. If the target state is the same, no update is posted.

sendCommand vs postUpdate: If you want to tell something to change (turn a light on, change the thermostat to a new temperature, start raising the blinds, etc.), then you want to send a command to an Item using sendCommand. If your Items’ states are not being updated by a binding, the autoupdate feature or something else external, you will probably want to update the state in a rule using postUpdate.

Unfortunately, most decimal fractions cannot be represented exactly as binary fractions. A consequence is that, in general, the decimal floating-point numbers you enter are only approximated by the binary floating-point numbers actually stored in the machine. Therefore, comparing the stored value with the new value will most likely always result in a difference. You can supply the named argument floatPrecision to round the value before comparing.

Parameters

  • item_or_item_name (Item or str) – name of the Item

  • new_value (State or Command) – state to update the Item with, or Command if using sendACommand (must be of a type supported by the Item)

  • sendACommand (Boolean) – (optional) True to send a command instead of an update

  • floatPrecision (int) – (optional) the precision of the Item’s state to use when comparing values

Returns

True, if the command or update was sent, else False

Return type

bool

core.utils.send_command_if_different(item_or_item_name, new_value, floatPrecision=None)

See postUpdateCheckFirst

core.utils.sendCommandCheckFirst(item_or_item_name, new_value, floatPrecision=None)

See postUpdateCheckFirst

core.utils.validate_channel_uid(channel_uid_or_string)
This function validates whether a ChannelUID exists or if a ChannelUID is

valid.

Parameters

channel_uid_or_string (ChannelUID or string) – the ChannelUID

Returns

None, if the ChannelUID does not exist or the ChannelUID is not in a valid format, else validated ChannelUID

Return type

ChannelUID or None

core.utils.validate_uid(uid)

This function validates UIDs.

Parameters

uid (string or None) – the UID to validate or None

Returns

a valid UID

Return type

string