Learn. Code. Enjoy!

Since the Domain Navigator is part of IoT Catalyst SDK, the user has two options in order to use it:
 a) Import and use the Navigator inside a Digital Thing
 b) Import and use the Navigator after activating the virtualenv of a IoT Catalyst Hypervisor

The import statement is:

from sdk.navigator.IoTCDomainNavigator import *

my_navigator = IoTCatalyst(<Studio IP>, {"type": "credentials", "userid": <userid>, "password": <password>} [, <permissive_mode>] [, <verbosity>])
# or alternatively
my_navigator = IoTCatalyst(<Studio IP>, {"type": "passport", "passport": <passport>} [, <permissive_mode>] [, <verbosity>])

 - <Studio IP> is the IP address of an IoT Catalyst Studio Instance.
 - <userid> is the user to authenticate to an IoT Catalyst Studio Instance.
 - <password> is the password to authenticate to an IoT Catalyst Studio Instance.
 - <passport> is the hash code generated by an IoT Catalyst Studio Instance when an object is created (hypervisor, container, adapter).
 - <permissive_mode> can be either True or False and sets the fact that, when encountering a handled Exception, the Navigator prints the error and throws it to the user (permissive_mode=False) or simply prints the error and returns None to the user (permissive_mode=True).
 - <verbosity> can be either “INFO”, “WARNING” or “ERROR” and sets the verbosity level of what the Navigator prints.

The default behaviour is that when a Function or Action gets called and it takes longer than the IoT Catalyst Studio parameter “CERTIFIED_PUBLISH_TIMEOUT_SEC” to execute, an error is raised. If one wants to change such timeout for the duration of the script it is sufficient to call the change_timeout method on the Navigator object and to pass an integer value as argument:
 <navigator>.change_timeout(<seconds>)

my_navigator.change_timeout(20)

The Navigator can use only one between the following two scopes: domain or local. Once opted for one of them, the scope can’t be changed during the script execution.
A domain scope is available by typing:
 <navigator>.domain
For a local scope:
 <navigator>.local
For ease of use, the remaining part of this API reference has been split in sections, based on the different IoT Catalyst types of components.

It is possible to access a Hypervisor by typing:
<navigator>.<Hypervisor name>

my_hypervisor = my_navigator.MyHypervisor

As an alternative to the dot notation, it is possible to access a Hypervisor using the get method on a navigator object:
 <navigator>.get(<Hypervisor name>)

my_hypervisor = my_navigator.get("MyHypervisor")

In the remaining part of this API reference the dot notation will be used to access a Hypervisor.
Note: accessing a Hypervisor implicitly tries to make use of a domain scope, thus the previous statement can throw an error in case a local scope has already been declared.

Hypervisor API List

To Start an Hypervisor:

my_navigator.MyHypervisor.ctrl.start()

To Stop an Hypervisor:

my_navigator.MyHypervisor.ctrl.stop()

To Update an Hypervisor:

my_navigator.MyHypervisor.ctrl.update()

To get an Hypervisor Status:

status = my_navigator.MyHypervisor.ctrl.status
print(status)

It is possible to access a Container by typing:
 <navigator>.<scope>.<Container name>

my_container = my_navigator.domain.MyContainer

It is possible to access a Container also through its Hypervisor:
 <navigator>.<Hypervisor name>.<Container name>

my_container = my_navigator.MyHypervisor.MyContainer

As an alternative to the dot notation, it is possible to access a Container using the get method on a scope or Hypervisor object:
 <navigator>.<scope>.get(<Container name>)
 <navigator>.<Hypervisor name>.get(<Container name>)

my_container = my_navigator.domain.get("MyContainer")
# OR
my_container = my_navigator.MyHypervisor.get("MyContainer")

In the remaining part of this API reference the dot notation will be used to access a Container.

Container API List

To Start a Container

my_navigator.domain.MyContainer.ctrl.start()

To Stop a Container

my_navigator.domain.MyContainer.ctrl.stop()

To Restart a Container

my_navigator.domain.MyContainer.ctrl.restart()

To Remount a Container

my_navigator.domain.MyContainer.ctrl.remount()

To Retrieve the status of a Container

status = my_navigator.domain.MyContainer.ctrl.status
print(status)

To Retrieve the current value of all updatable features of a Container

udfs = my_navigator.domain.MyContainer.ctrl.get_all_udfs()
print(udfs)

To execute a function of a container

new_speed = my_navigator.domain.MyActuator.increaseFanSpeed()
print(new_speed)

To execute an action of a container

my_navigator.domain.MyActuator.turnOnFan()

To get all settings of a container

settings = my_navigator.domain.MySensor.settings.get_all()
print(settings)

To get the value of a setting of a container

setting_value = my_navigator.domain.MySensor.settings.POLLING_TIME_DATA.value
print(setting_value)

To set the value of a setting of a container

my_navigator.domain.MySensor.settings.POLLING_TIME_DATA.value = 10

To print all settings of a container

my_navigator.domain.MySensor.settings.print_all()

It is possible to access a Feature by typing:
 <navigator>.<scope>.<Container name>.<Feature name>

my_navigator.domain.MyContainer.MyFeature

As an alternative to the dot notation, it is possible to access a Feature using the get method on a Container object:
 <navigator>.<scope>.<Container name>.get(<Feature name>)

my_navigator.domain.MyContainer.get("MyFeature")

In the remaining part of this API reference the dot notation will be used to access a Feature.

Feature API List

To get the value of a feature

value = my_navigator.domain.MySensor.Potential.value
print(value)

To set the value of a feature

my_navigator.domain.MySensor.mySetpoint.value = 20

To get the last known value of a feature

value = my_navigator.domain.MySensor.Potential.last_known_value
print(value)

To get the numebr of updates of a feature

updates = my_navigator.domain.MySensor.Potential.updates
print(updates)

To get the first update of a feature

first_update = my_navigator.domain.MySensor.Potential.first_update
print(first_update)

To get the last update of a feature

last_update = my_navigator.domain.MySensor.Potential.last_update
print(last_update)

To set the ttl of a feature

my_navigator.domain.MySensor.Potential.ttl = 10

To get the ttl of a feature

ttl = my_navigator.domain.MySensor.Potential.ttl
print(ttl)

To get the max value of a feature (numeric only)

max = my_navigator.domain.MySensor.Potential.max
print(max)

To get the min value of a feature (numeric only)

min = my_navigator.domain.MySensor.Potential.min
print(min)

To get the average value of a feature (numeric only)

average = my_navigator.domain.MySensor.Potential.avg
print(average)

To get all stats of a feature

stats = my_navigator.domain.MySensor.Potential.get_stats()

To print all stats of a feature

my_navigator.domain.MySensor.Potential.print_stats()

To clear all stats of a feature

my_navigator.domain.MySensor.Potential.clear_stats()

To set a callback on an event feature start

my_navigator.domain.DoorSensor.DoorOpen.on_event_start(myCallback, myArg1, myArg2)
myCallback(current_value, arg1, arg2)

To remove a callback on an event feature start

my_navigator.domain.DoorSensor.DoorOpen.rm_on_event_start()

To set a callback on an event feature end

my_navigator.domain.DoorSensor.DoorOpen.on_event_end(myCallback, myArg1, myArg2)
myCallback(current_value, arg1, arg2)

To remove a callback on an event feature end

my_navigator.domain.DoorSensor.DoorOpen.rm_on_event_end()

To set a callback on a data feature change (string only)

my_navigator.domain.DoorSensor.DoorStatus.on_change(myCallback, myArg1, myArg2)
myCallback(current_value, arg1, arg2)

to remove a callback on a data feature change (string only)

my_navigator.domain.DoorSensor.DoorStatus.rm_on_change()

to set a callback on a data feature value limit overflow (numeric only)

my_navigator.domain.mySensor.Potential.on_limit_overflow (myCallback, 9, 26, myArg1, myArg2)
myCallback(current_value, arg1, arg2)

To remove a callback on a data feature value limit overflow (numeric only)

my_navigator.domain.mySensor.Potential.rm_on_limit_overflow()

To set a callback on a data feature percentage limit overflow (numeric only)

my_navigator.domain.mySensor.Potential.on_percentage_overflow(myCallback, 5, 10, myArg1, myArg2)
myCallback(current_value, arg1, arg2)

To remove a callback on a data feature percentage limit overflow (numeric only)

my_navigator.domain.mySensor.Potential.rm_on_percentage_overflow()