kepconfig.iot_gateway.iot_items

  1# -------------------------------------------------------------------------
  2# Copyright (c) PTC Inc. and/or all its affiliates. All rights reserved.
  3# See License.txt in the project root for
  4# license information.
  5# --------------------------------------------------------------------------
  6
  7
  8r"""`iot_items` exposes an API to allow modifications (add, delete, modify) to 
  9iot_items objects within the Kepware Configuration API
 10"""
 11
 12from typing import Union
 13from .. import utils
 14from ..connection import server
 15from .. import iot_gateway as IOT
 16from ..error import KepError, KepHTTPError
 17from ..utils import _url_parse_object
 18
 19IOT_ITEMS_ROOT = '/iot_items'
 20
 21def _create_url(tag = None):
 22    '''Creates url object for the "iot items" branch of Kepware's IoT Agents property model. Used 
 23    to build a part of Kepware Configuration API URL structure
 24    
 25    Returns the device specific url when a value is passed as the iot item name.
 26    '''
 27    if tag == None:
 28        return IOT_ITEMS_ROOT
 29    else: 
 30        normalized_tag = utils._address_dedecimal(tag)
 31        return '{}/{}'.format(IOT_ITEMS_ROOT, _url_parse_object(normalized_tag))
 32
 33
 34def add_iot_item(server: server, DATA: Union[dict, list], agent: str, agent_type: str) -> Union[bool, list]:
 35    '''Add a `"iot item"` or multiple `"iot item"` objects to Kepware's IoT Gateway agent. Additionally 
 36    it can be used to pass a list of iot items to be added to an agent all at once.
 37
 38    :param server: instance of the `server` class
 39    :param DATA: Dict or List of Dicts of the iot item or list of items
 40    expected by Kepware Configuration API
 41    :param agent: name of IoT Agent
 42    :param agent_type: agent type. Valid values are `MQTT Client`, `REST Client` or `REST Server`
 43
 44    :return: True - If a "HTTP 201 - Created" is received from Kepware server
 45    :return: If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
 46    iot items added that failed.
 47
 48    :raises KepHTTPError: If urllib provides an HTTPError
 49    :raises KepURLError: If urllib provides an URLError
 50    '''
 51    r = server._config_add(server.url + IOT.agent._create_url(agent_type, agent) + _create_url(), DATA)
 52    if r.code == 201: return True
 53    elif r.code == 207:
 54            errors = [] 
 55            for item in r.payload:
 56                if item['code'] != 201:
 57                    errors.append(item)
 58            return errors 
 59    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 60
 61def del_iot_item(server: server, iot_item: str, agent: str, agent_type: str) -> bool:
 62    '''Delete an `"iot item"` object in Kepware.
 63
 64    :param server: instance of the `server` class
 65    :param iot_item: IoT item to delete
 66    :param agent: name of IoT Agent
 67    :param agent_type: agent type. Valid values are `MQTT Client`, `REST Client` or `REST Server`
 68
 69    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 70
 71    :raises KepHTTPError: If urllib provides an HTTPError
 72    :raises KepURLError: If urllib provides an URLError
 73    '''
 74    r = server._config_del(server.url + IOT.agent._create_url(agent_type, agent) + _create_url(iot_item))
 75    if r.code == 200: return True 
 76    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 77
 78def modify_iot_item(server: server, DATA: dict, agent: str, agent_type: str, *, iot_item: str = None, force: bool = False) -> bool:
 79    '''Modify an `"iot item"` object and it's properties in Kepware. If a `"iot item"` is not provided as an input,
 80    you need to identify the iot item in the *'common.ALLTYPES_NAME'* property field in the `"DATA"`. It will 
 81    assume that is the iot item that is to be modified.
 82
 83    :param server: instance of the `server` class
 84    :param DATA: Dict of the iot item properties to be modified.
 85    :param agent: name of IoT Agent
 86    :param agent_type: agent type. Valid values are `MQTT Client`, `REST Client` or `REST Server`
 87    :param iot_item: *(optional)* name of IoT item to modify. Only needed if not existing in `"DATA"`
 88    :param force: *(optional)* if True, will force the configuration update to the Kepware server
 89    
 90    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 91
 92    :raises KepHTTPError: If urllib provides an HTTPError
 93    :raises KepURLError: If urllib provides an URLError
 94    '''
 95    
 96    agent_data = server._force_update_check(force, DATA)
 97    if iot_item == None:
 98        try:
 99            r = server._config_update(server.url + IOT.agent._create_url(agent_type, agent) + _create_url(agent_data['common.ALLTYPES_NAME']), agent_data)
100            if r.code == 200: return True 
101            else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
102        except KeyError as err:
103            err_msg = 'Error: No agent identified in DATA | Key Error: {}'.format(err)
104            raise KepError(err_msg)
105    else:
106        r = server._config_update(server.url + IOT.agent._create_url(agent_type, agent) + _create_url(iot_item), agent_data)
107        if r.code == 200: return True 
108        else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
109
110def get_iot_item(server: server, iot_item: str, agent: str, agent_type: str)-> dict:
111    '''Returns the properties of the `"iot item"` object.
112
113    :param server: instance of the `server` class
114    :param iot_item: name of IoT item to retrieve properties
115    :param agent: name of IoT Agent
116    :param agent_type: agent type. Valid values are `MQTT Client`, `REST Client` or `REST Server`
117
118    :return: Dict of properties for the iot item requested
119
120    :raises KepHTTPError: If urllib provides an HTTPError
121    :raises KepURLError: If urllib provides an URLError
122    '''
123    r = server._config_get(server.url + IOT.agent._create_url(agent_type, agent) + _create_url(iot_item))
124    return r.payload
125
126def get_all_iot_items(server: server, agent: str, agent_type: str, *, options: dict = None) -> list:
127    '''Returns the properties of all `"iot item"` objects for an agent.
128    
129    :param server: instance of the `server` class
130    :param iot_item: name of IoT item to retrieve properties
131    :param agent: name of IoT Agent
132    :param agent_type: agent type. Valid values are `MQTT Client`, `REST Client` or `REST Server`
133    :param options: *(optional)* Dict of parameters to filter, sort or pagenate the list of IoT items. Options are 'filter', 
134    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'. Only used when exchange_name is not defined.
135
136    :return: list of properties for all IoT items
137
138    :raises KepHTTPError: If urllib provides an HTTPError
139    :raises KepURLError: If urllib provides an URLError
140    '''
141    r = server._config_get(f'{server.url}{IOT.agent._create_url(agent_type, agent)}{_create_url()}', params= options)
142    return r.payload