KODE OSS starts your equipment at the latest possible moment to save runtime and energy while optimizing for comfort. OSS starts each device at the optimal time so that the zone temp is in the range of the cooling and heating setpoint range at your target time. Every building is different, and we use the OSS Adapter to tune our machine learning optimization to your building's data. 

In this article, you can expect to learn,

• Default roles with OSS configuration permissions

• The main purpose of the OSS adapter

• Device, point, and schedule requirements to run OSS

• The basics of navigation

• How to add an adapter

• How to edit an adapter

Default roles with OSS configuration permissions 

The user roles that have default permissions to configure OSS are:

• Super Admin

• System Admin

• System Integrator

• Engineering Manager

Device, point, and schedule requirements to run OSS

OSS supports multiple HVAC system architectures, and the primary purpose of the adapter is to specify which devices should be included in the optimization and what points/parameters should be used to control the equipment. This can vary building to building, and adapting is very straightforward.

Some of the most common HVAC system architectures to activate OSS on are:

• VAV - AHU

• VAV - AHU - AHU

• FCU

• AHU

Our base machine-learning model requires the following points:

• Zone Air Temperature

• Zone Air Temperature Cooling Setpoint

• Zone Air Temperature Heating Setpoint

• Run Status

• Occupied Mode

Point fields to fill in	Description	Points applicable	Type
Zone Air Temperature Sensor	This field allows you to select the sensor that measures Zone Air Temperature for the zone you want to optimize. The Zone Air Temperature Sensor determines the temperature in a location.	Zone_air_temperature_sensor	Sensor
Zone Air Temperature Cooling Setpoint	This field allows you to select the Zone Air Temperature Setpoint for Cooling. This Setpoint will keep the Cooling temperature at a desired range. Select Zone Air Temperature Cooling Setpoint based on how your device has been programed, you may have an effective cooling setpoint, an occupied cooling setpoint, a zone temp setpoint etc.	Effective_zone_air_temperature_setpoint Zone_air_temperature_setpoint Occupied_cooling_zone_air_temperature_setpoint Effective_cooling_zone_air__tempertaure_sepoint Return_air_temperature_setpoint	Setpoint
Zone Air Temperature Heating Setpoint	This field allows you to select the Zone Air Temperature Setpoint for Heating. This Setpoint will keep the Heating temperature at a desired range. When selecting the Zone Air Temperature Heating Setpoint, a device may have an effective heating setpoint, an occupied heating setpoint, a zone temp setpoint, etc.	Effective_zone_air_temperature_setpoint Zone_air_temperature_setpoint Occupied_heating_zone_air_temperature_setpoint Effective_heating_zone_air__tempertaure_sepoint Return_air_temperature_setpoint	Setpoint
Run Status	This field allows you to select a point that indicates whether the device is ON or OFF	Run_status, Occupied_mode	Sensor
Occupied Mode	This field allows you to select a point that will serve to override the device from OFF to ON and vice versa. Must be writable.	Enable_command, Occupied_mode	Control

Note: Ideally, for OSS to work, there should be at least 15-20 devices with at least 15 days of good data (occupied mode and run status, have been switching ON and OFF regularly).

Schedules 

The schedules feature allows you to manage the functioning schedules of various devices that are connected in a building. From here, Schedules can:

• View, modify, delete numeric, boolean, string, or enum schedules as required. 

• Create Special Events. Using a calendar-style interface, schedule single dates, date ranges, or weekly schedules. 

Go to the Schedules feature from the left-hand navigation bar. At the top right-click on the icon “New Schedule”.
A window named “ Create New Schedule” will open. 

From here, the Schedules can be created. Please refer here(https://help.kodelabs.com/portal/en/kb/articles/schedules-options-and-features#Create_a_New_Schedule)  for more details regarding the Schedule navigation article.

Schedules provide the ability to set up automated scheduling for devices in order to maximize efficiency, reduce energy costs, and save money while allowing the users to monitor and modify settings in KODE OS, making it easier to make changes without having to enter the building.

The relationship between the Schedule and OSS is a very important part of the BMS. OSS works with your BMS to choose the most efficient start and stop times for each day based on your Schedule configuration. Schedule is considered one of the most crucial points of the OSS Adapter, since without it, the devices(batches) can not be linked together and automatically turned on/off.

Let's take an Example: In an office building in Detroit, the occupancy hours are from 8:30 am to 5:30 pm Monday to Friday. The BMS starts the HVAC system via a schedule at 6:00 am to ensure that space conditions are achieved before occupants arrive.

After the introduction of OSS, we adjusted the start time of the schedules from 6:00 am to 8:30 am. 8:30 am becomes the target satisfaction time, and OSS will ensure the equipment is started before 8:30 am as needed. This reduction in operating hours per day represented a considerable reduction in the operation of the HVAC system of a considerable number of percent, which led to energy saving for that building as well. 

Do Not!

1. Schedules should not be set up in a way that when the Air Handling Unit AHU_1 turns on, it also enables the VAVs that are connected to it (VAV_1, VAV_2,…, VAV_N). This will be the OSS Adapter job.

2. When a Schedule is connected to another Schedule and controls the device.

3. When the Enum Schedule has a Point, Mapper, or Switch that controls the devices.

Do!

All the logic configurations in Jace that turn on the devices should be turned off except the Schedulers that control both the base device and the reference device; otherwise, OSS can not control the devices.

OSS Adapter Navigation

Go to your company's KODE OS instance, then navigate to the Schedules icon from the left main bar, and click on OSS at the top right tab of the screen to get to the OSS Adapter.

Upon selecting the OSS tab, you can see the Optimizations that are in place already (if applicable) with all the details: name of the Schedule, Devices, Floors, and Occupancy Start/Stop.

On this page, you have the ability to select your OSS operation mode. There are three Operation Modes available: 

Comfort - The goal of Comfort is to have all zones on setpoints by the time occupancy starts. The focus is
on occupant comfort.

Balanced – The goal is to have the third quartile of the zones on setpoint by the time occupancy starts.
The focus is on occupant comfort as well as energy savings.

Energy Savings – The goal is to have the medium of the zones on setpoint by the time occupancy starts.
The focus is on energy savings.

Click on the Adapters button on the upper right, as highlighted in the screenshot, which will open the page with more details. 

To add a new Adapter, click on Add OSS Adapter, there are two options:

• Create a new Adapter

• Add from the existing (Templated Adapters) 

Adding a new Adapter

After clicking on Add New Adapter, the page with these details will be displayed.

The process of creating a new Adapter is categorized as follows:

            1) Select Devices > 2) Add Points > 3) Review and verify

1) On the Select Devices page, we have the Details with the Name, Description, Base Device,
and Reference Device of the adapter:

See screenshot below for more details:

• Name of the Adapter: FCU with Effective Setpoints (the name can be customized to your liking, depending on the function).

• Description: Default FCU adapter with Effective Setpoints.

• Base Device: fcu_1 (devices can be added here, a kind reminder: devices are exclusive to one adapter).

• At the base Device, select the devices by choosing their Canonical Types. Also, select the Entities of your device and click save.
  
  

• Reference Device:  Is filled depending on the type of device that is chosen for the OSS Adapter. For example, VAVs are referenced to an AHU, and in order for OSS to work properly, we need data points from both device types.  If a chosen device is not connected to any other device, we can ignore the Reference Device option. If a device is connected to another device, then we can use the Reference Device feature.

2) On the second page, Add Points, as per the name, points should be added to the Base Device for each of the fields
presented. Upon selecting Choose Points, you can select the Points for the sensors and add them. 

Here you have five options:

• -Zone Air Temperature Sensor

• -Zone Air Temperature Cooling Setpoint

• -Zone Air Temperature Heating Setpoint

• -Run Status

• -Occupied Mode(should be writable)
  
  If a Reference Device is selected in step one, then another two options will be added for Reference Device:

• Run status

• Occupied mode 

Let's take an example when creating an adapter for VAV-AHU devices with Zone Air Temperature Setpoint. With Base Device a VAV and Reference Device an AHU. 

At the Add Point tab, we will have seven fields of points to fill in.

Base Device:

• At the Zone Air Temperature Sensor, select the zone air temperature sensor.

• At Zone Air Temperature Cooling Setpoint, select the zone air temperature setpoint.

• At Zone Air Temperature Heating Setpoint, select the zone air temperature setpoint.

• At Run status, select occupied mode, and for ON status choose Occupied, for OFF choose Unoccupied.

• In Occupied mode, select Occupied mode, and for ON status choose Occupied, for OFF choose Unoccupied.

Reference Device

• Run status select occupied mode, and for ON status choose Occupied, for OFF choose Unoccupied.

• Occupied mode select occupied mode, and for ON status choose Occupied, for OFF choose Unoccupied.

Let's take another example when creating an adapter for VAV-AHU with Effective Setpoints. This will be an Adapter for devices that use Effective Cooling/Heating Temperature Setpoints. With Base Device a VAV and Reference Device an AHU. 

At the Add Point tab, we will have seven fields of points to fill in.

Base Device:

• At the Zone Air Temperature Sensor, select the zone air temperature sensor.

• At Zone Air Temperature Cooling Setpoint, select the effective cooling zone air temperature setpoint.

• At Zone Air Temperature Heating Setpoint, select the effective heating zone air temperature setpoint.

• At Run status, select occupied mode, and for ON status choose Occupied, for OFF choose Unoccupied.

• In Occupied mode, select Occupied mode and for ON status choose Occupied, for OFF choose Unoccupied.

Reference Device

• Run status select occupied mod, or any other point that will give the device status, for ON status, choose Occupied, and for OFF choose Unoccupied. 

• Occupied mode select occupied mode, and for ON status choose Occupied, for OFF choose Unoccupied.

If a device has more than one point of the same field, select the Aggregation function. The Aggregate function performs a calculation on a set of values and returns a single value. At  Zone Air Temperature Cooling Setpoint and Zone Air Temperature Heating Setpoint, besides that, we have an Aggregation function, there are also an upper band and a lower band that represent the time when the device will start cooling or heating.

If the Zone Air Temperature Setpoint, for example, is 23 Celsius, the Avg function is plus 1 for the Cooling Setpoint, and the Avg function is minus 1  for the Heating Setpoint, then the upper bound will be 24 Celsius, and the lower bound will be 22 Celsius.

At the Run Status and Occupied Mode enums can be mapped, which maps the values coming from these points to occupied and unoccupied. 

There is a requirement to have at least one occupied_mode as a writable point on either the  Optimizing or Reference device; having two or more occupied_mode points is acceptable too.

To edit the point selected, click on the icon. Once clicking, it will open the tab with the points from where you can modify and add more points, or edit the point aggregation.

3) The last page is Review and Verify

This page is split into two tabs: Completed Devices and Devices With Issues.

The first tab, Completed Devices, shows all the devices that meet OSS requirements fully, which means they have all of the required points, they have schedules in place and referenced to devices, and OC mode points are writable.

For the process to be completed, we must select the devices that we want to include on the Adapter and click Save.

Navigate back to Operation Mode and see in the Bottom right the icon for OSS activation.

Click on Activate and wait for a few minutes until the OSS is active. After that, the OSS Adapter will turn on for the devices that we have selected.

The second tab, Devices With Issue, shows devices that do not meet OSS requirements fully. From this page, you can click on devices directly and continue to make necessary adjustments.

After filling in the data in the Select Devices, Add Points, and saving them on the Review and Verify page, the adapter process will be completed. See below an example of an OSS Adapter.

Click on Add from Existing, and a window will open with the Adapters from the library. Here, you may select a specific template and click on Add From Existing to save.

Our team has created adapter templates for every supported use case. In the screenshot below, you can find a list of templates that are provided by default.

After adding the Adapter from the existing templates, steps 1 and 2 of the adapter creation process will be prefilled from the templates. Also, keep in mind that you will have to create new OSS Adapters for each building.

Existing templates are editable. After choosing the specific template, the process of creating the adapter will start from the beginning, only with the first and second steps prefilled. In the first and second steps (Selecting Devices and Add Points), changes can be made and then saved in the third step (Review and Verify).

Edit and Delete OSS Adapter

To delete the OSS Adapter, click on the three dots on the upper right and select the trash icon. From there, the confirmation page for deletion will be open

To edit the OSS Adapter, click on the three dots icon at the far right of the Adapter name > from the drop-down menu select the Edit icon. From there, you will be directed to the Edit OSS Adapter page, from where you can modify it.