tuwien.auto.calimero.mgmt.PropertyAccess Maven / Gradle / Ivy
Show all versions of calimero-core Show documentation
/*
Calimero 2 - A library for KNX network access
Copyright (c) 2010, 2023 B. Malinowsky
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Linking this library statically or dynamically with other modules is
making a combined work based on this library. Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.
As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under terms
of your choice, provided that you also meet, for each linked independent
module, the terms and conditions of the license of that module. An
independent module is a module which is not derived from or based on
this library. If you modify this library, you may extend this exception
to your version of the library, but you are not obligated to do so. If
you do not wish to do so, delete this exception statement from your
version.
*/
package tuwien.auto.calimero.mgmt;
import tuwien.auto.calimero.KNXException;
import tuwien.auto.calimero.dptxlator.DPTXlator;
/**
* Common property services for accessing KNX properties and property descriptions.
*
*
* @author B. Malinowsky
*/
public interface PropertyAccess
{
/**
* Defines property identifiers (PIDs) for global properties (interface object type =
* global), Device object, Router object, cEMI Server object, and KNXnet/IP parameter object.
*
* Users are encouraged to use these more descriptive name constants instead of plain
* PID integer values for better readability.
*
* @author B. Malinowsky
*/
interface PID
{
//
// global properties (server object type = global)
//
/**
* Global property "Interface Object Type".
*
* Object Type Device Object.
*/
// PDT,DPT: PDT_UNSIGNED_INT,DPT_PropDataType
int OBJECT_TYPE = 1;
/**
* Global property "Interface Object Name".
*
* Name of the Interface Object.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR[]
int OBJECT_NAME = 2;
/**
* Global property "Load Control".
*
* Access to load state machines.
*/
// PDT,DPT: PDT_CONTROL
int LOAD_STATE_CONTROL = 5;
/**
* Global property "Run Control".
*
* Access to run state machines.
*/
// PDT,DPT: PDT_CONTROL
int RUN_STATE_CONTROL = 6;
/**
* Global property "Table Reference".
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int TABLE_REFERENCE = 7;
/**
* Global property "Service Control".
*
* Service Control, Permanent Control field for the Device.
*/
// PDT,DPT: PDT_UNSIGNED_INT
int SERVICE_CONTROL = 8;
/**
* Global property "Firmware Revision".
*
* Revision number of the Firmware.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int FIRMWARE_REVISION = 9;
/**
* Global property "KNX Serial Number".
*
* KNX Serial Number of the device.
*/
// PDT,DPT: PDT_GENERIC_06
int SERIAL_NUMBER = 11;
/**
* Global property "Manufacturer Identifier".
*
* Manufacturer code.
*/
// PDT,DPT: PDT_UNSIGNED_INT
int MANUFACTURER_ID = 12;
/**
* Global property "Application Version".
*
* Version of the Application Program.
*/
// PDT,DPT: PDT_GENERIC_05
int PROGRAM_VERSION = 13;
/**
* Global property "Device Control".
*
* Device Control, Temporary Control field for the Device.
*/
// PDT,DPT: PDT_BISET8,DPT_Device_Control
int DEVICE_CONTROL = 14;
/**
* Global property "Order Info".
*
* OrderInfo, Manufacturer specific Order ID.
*/
// PDT,DPT: PDT_GENERIC_10
int ORDER_INFO = 15;
/**
* Global property "PEI Type".
*
* Connected or required PEI-type.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int PEI_TYPE = 16;
/**
* Global property "PortADDR".
*
* PortAddr, Direction bits for Port A.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int PORT_CONFIGURATION = 17;
/**
* Global property "Pollgroup Settings".
*
* Pollgroup settings (polling group and slot number).
*/
// PDT,DPT: PDT_POLL_GROUP_SETTINGS
int POLL_GROUP_SETTINGS = 18;
/**
* Global property "Manufacturer Data".
*
* Manufacturer Data.
*/
// PDT,DPT: PDT_GENERIC_04
int MANUFACTURER_DATA = 19;
/**
* Global property "Description".
*
* Description, Description of the device.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR[ ]
int DESCRIPTION = 21;
/**
* Global property "Address Table Format 0".
*
* Group Address Table, Association Table.
*/
// PDT,DPT: PDT_UNSIGNED_INT[]
int TABLE = 23;
/**
* Global property "Interface Object Link".
*
* enrollment status, A-Mode enrollment.
*/
// PDT,DPT: PDT_FUNCTION
// this property is specified uses British spelling
int ENROL = 24;
/**
* Global property "Version".
*
* Generic version information.
*/
// PDT,DPT: PDT_VERSION (U6U6U6)
int VERSION = 25;
/**
* Global property "Memory Control Table".
*
* Sub-segmentation of memory space and checksum.
*/
// PDT,DPT: PDT_GENERIC_07[]
int MCB_TABLE = 27;
/**
* Global property "Error code".
*
* Error code when load state machine indicates "error".
*/
// PDT,DPT: PDT_GENERIC_01
int ERROR_CODE = 28;
/**
* Global property "Object Index".
*
* Access to the object index of a function block.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int OBJECT_INDEX = 29;
//
// properties of object type 0, Device Object
//
/**
* Device object property "Programming Mode".
*
* Bit Set:
* Bit 0 (LSB) - programming mode: 1 = device is in programming mode, 0 = device
* is not in programming mode (i.e., equal to KNX property of device status)
* Bits 1 to 7 - reserved
*/
// PDT,DPT: PDT_BITSET8
int PROGMODE = 54;
/**
* Device object property "Max. APDU-Length".
*
* Maximum APDU length.
*/
// PDT,DPT: PDT_UNSIGNED_INT
int MAX_APDULENGTH = 56;
/**
* Device object property "Subnetwork Address".
*
* KNX subnet address, i.e., the high octet of the KNX individual address.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int SUBNET_ADDRESS = 57;
/**
* Device object property "Device Address".
*
* Device address, i.e., the low octet of the KNX individual address.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int DEVICE_ADDRESS = 58;
/**
* Device object property "Domain Address".
*
* Domain address of a KNX device.
*/
// PDT,DPT: PDT_UNSIGNED_INT
int DOMAIN_ADDRESS = 70;
/**
* Device object property "Interface Object List".
*
* Used with cEMI functionality.
*/
// PDT,DPT: PDT_UNSIGNED_INT
int IO_LIST = 71;
/**
* Device object (object type 0) property "RF domain address".
*/
int RF_DOMAIN_ADDRESS = 82;
/**
* Device object property "Device Descriptor Type 0".
*/
// PDT,DPT: PDT_GENERIC_02
int DEVICE_DESCRIPTOR = 83;
//
// properties of object type 6, Router object
//
/**
* Router object property "Line Status", status of the subnetwork connected to the secondary
* side of the coupler. Bit 0 = PowerDownSubline: 0 = power up, 1 = power down.
*/
int LINE_STATUS = 51;
/**
* Router object property "Medium Status", status of the communication medium connected to the communication
* interface. Bit 0 = Communication: 0 = possible, 1 = impossible.
*/
int MEDIUM_STATUS = 51;
/**
* Router object property "Main Line Coupler Config", for point-to-point and broadcast
* frames on the primary side subnetwork of the coupler.
*/
int MAIN_LCCONFIG = 52;
/**
* Router object property "Sub Line Coupler Config", for point-to-point and broadcast
* frames on the secondary side subnetwork of the coupler.
*/
int SUB_LCCONFIG = 53;
/**
* Router object property "Main Line Coupler Group Config", for multicast
* frames (group communication) on the primary side subnetwork of the coupler.
*/
int MAIN_LCGROUPCONFIG = 54;
/**
* Router object property "Sub Line Coupler Group Config", for multicast
* frames (group communication) on the secondary side subnetwork of the coupler.
*/
int SUB_LCGROUPCONFIG = 55;
//
// properties of object type 8, cEMI server object
//
/**
* Object type 8 property "Medium Type".
*
* KNX media types supported by server.
* Bit 0 (LSB): reserved (formerly TP0)
* Bit 1: TP1
* Bit 2: PL110
* Bit 3: RF
* Bit 4 - 15 (MSB): reserved
*/
int MEDIUM_TYPE = 51;
/**
* cEMI server object (object type 8) property "Communication mode".
*/
int COMM_MODE = 52;
/**
* cEMI server object (object type 8) property "cEMI client subnetwork address", i.e., the subnetwork address
* part of a KNX Individual Address.
*/
int CLIENT_SNA = 57;
/**
* cEMI server object (object type 8) property "Device address of the cEMI client", i.e., the device part of a
* KNX Individual Address.
*/
int CLIENT_DEVICE_ADDRESS = 58;
/**
* cEMI server object (object type 8) property "Selected RF mode".
*/
int RF_MODE_SELECT = 60;
/**
* cEMI server object (object type 8) property "Supported RF modes".
*/
int RF_MODE_SUPPORT = 61;
/**
* cEMI server object (object type 8) property "cEMI supported communication modes" (property datatype: PDT_BITSET16).
*/
int COMM_MODES_SUPPORTED = 64;
/**
* cEMI server object (object type 8) property "Supported filtering modes".
*/
int FILTERING_MODE_SUPPORT = 65;
/**
* cEMI server object (object type 8) property "Selected filtering modes".
*/
int FILTERING_MODE_SELECT = 66;
//
// properties of object type 11, KNXnet/IP parameter object
//
/**
* Object type 11 property "Project Installation Identification".
*
* Identification of the project and the installation in which this KNXnet/IP
* device resides.
*/
// PDT,DPT: PDT_UNSIGNED_INT
int PROJECT_INSTALLATION_ID = 51;
/**
* Object type 11 property "KNX Individual Address".
*
* Individual Address of the KNXnet/IP server.
*/
// PDT,DPT: PDT_UNSIGNED_INT
int KNX_INDIVIDUAL_ADDRESS = 52;
/**
* Object type 11 property "Additional Individual Addresses".
*
* Sorted list of additional KNX Individual Addresses for KNXnet/IP routers and
* tunneling servers.
*/
// PDT,DPT: PDT_UNSIGNED_INT[]
int ADDITIONAL_INDIVIDUAL_ADDRESSES = 53;
/**
* Object type 11 property "Current IP Assignment Method".
*
* Used IP address assignment method.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int CURRENT_IP_ASSIGNMENT_METHOD = 54;
/**
* Object type 11 property "IP Assignment Method".
*
* Enabled IP assignment methods that can be used.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int IP_ASSIGNMENT_METHOD = 55;
/**
* Object type 11 property "IP Capabilities".
*
* Capabilities of the KNXnet/IP device for obtaining an IP address.
*/
// PDT,DPT: PDT_BITSET_8
int IP_CAPABILITIES = 56;
/**
* Object type 11 property "Current IP Address".
*
* Currently used IP address.
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int CURRENT_IP_ADDRESS = 57;
/**
* Object type 11 property "Current Subnet Mask".
*
* Currently used IP subnet mask.
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int CURRENT_SUBNET_MASK = 58;
/**
* Object type 11 property "Current Default Gateway".
*
* IP Address of the KNXnet/IP device's default gateway.
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int CURRENT_DEFAULT_GATEWAY = 59;
/**
* Object type 11 property "IP Address".
*
* Configured fixed IP Address.
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int IP_ADDRESS = 60;
/**
* Object type 11 property "Subnet Mask".
*
* Configured IP subnet mask.
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int SUBNET_MASK = 61;
/**
* Object type 11 property "Default Gateway".
*
* Configured IP address of the default gateway.
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int DEFAULT_GATEWAY = 62;
/**
* Object type 11 property "DHCP/BootP Server".
*
* IP address of the DHCP or BootP server from which the KNXnet/IP device received
* its IP address.
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int DHCP_BOOTP_SERVER = 63;
/**
* Object type 11 property "MAC Address".
*
* MAC address of the KNXnet/IP device.
*/
// PDT,DPT: PDT_GENERIC_06
int MAC_ADDRESS = 64;
/**
* Object type 11 property "System Setup Multicast Address".
*
* KNXnet/IP system set-up multicast address. Value is fixed to 224.0.23.12.
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int SYSTEM_SETUP_MULTICAST_ADDRESS = 65;
/**
* Object type 11 property "Routing Multicast Address".
*
* Routing multicast address.
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int ROUTING_MULTICAST_ADDRESS = 66;
/**
* Object type 11 property "Time To Live".
*
* TTL value to be used by KNXnet/IP devices.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int TTL = 67;
/**
* Object type 11 property "KNXnet/IP Device Capabilities".
*
* KNXnet/IP protocols supported by the KNXnet/IP device.
*/
// PDT,DPT: PDT_BITSET_16
int KNXNETIP_DEVICE_CAPABILITIES = 68;
/**
* Object type 11 property "KNXnet/IP Device State".
*
* Various KNXnet/IP device status info, like KNX or IP network connection failure.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int KNXNETIP_DEVICE_STATE = 69;
/**
* Object type 11 property "KNXnet/IP Routing Capabilities".
*
* Supported features by the KNXnet/IP Router.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int KNXNETIP_ROUTING_CAPABILITIES = 70;
/**
* Object type 11 property "Priority FIFO Enabled".
*
* Indication of whether the priority FIFO is enabled of disabled.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR
int PRIORITY_FIFO_ENABLED = 71;
/**
* Object type 11 property "Queue Overflow to IP".
*
* Number of telegrams lost due to overflow of queue to IP.
*/
// PDT,DPT: PDT_UNSIGNED_INT
int QUEUE_OVERFLOW_TO_IP = 72;
/**
* Object type 11 property "Queue overflow to KNX".
*
* Number of telegrams lost due to overflow of queue to KNX.
*/
// PDT,DPT: PDT_UNSIGNED_INT
int QUEUE_OVERFLOW_TO_KNX = 73;
/**
* Object type 11 property "Telegrams Transmitted to IP".
*
* Number of telegrams successfully transmitted to IP.
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int MSG_TRANSMIT_TO_IP = 74;
/**
* Object type 11 property "Telegrams Transmitted to KNX".
*
* Number of telegrams successfully transmitted to KNX.
*/
// PDT,DPT: PDT_UNSIGNED_LONG
int MSG_TRANSMIT_TO_KNX = 75;
/**
* Object type 11 property "Friendly Name".
*
* Human Readable Friendly Name.
*/
// PDT,DPT: PDT_UNSIGNED_CHAR[30]
int FRIENDLY_NAME = 76;
/**
* Object type 11 property "Routing Busy Wait Time".
*
* The time wait value sent with a routing busy indication, with default value 100 ms.
* PDT: PDT_UNSIGNED_INT
* Implementations of masks 0x091A and 0x5705 may not have this property.
*/
int ROUTING_BUSY_WAIT_TIME = 78;
}
/**
* Sets one element of a property, with the value given as string representation.
*
* The value is translated according the associated property data type.
*
* @param objIndex interface object index in the device
* @param pid property identifier
* @param position property index in the array where to set the element value
* @param value string representation of the element value
* @throws KNXException on adapter errors while setting the property elements or
* translation problems
* @throws InterruptedException on thread interrupt
*/
void setProperty(int objIndex, int pid, int position, String value)
throws KNXException, InterruptedException;
/**
* Sets one or more elements of a property.
*
* @param objIndex interface object index in the device
* @param pid property identifier
* @param start index of the first array element to set
* @param elements number of elements to set in the property
* @param data byte array holding the element data
* @throws KNXException on adapter errors while setting the property elements
* @throws InterruptedException on thread interrupt
*/
void setProperty(int objIndex, int pid, int start, int elements, byte... data)
throws KNXException, InterruptedException;
/**
* Gets one or more elements of a property.
*
* @param objIndex interface object index in the device
* @param pid property identifier
* @param start index of the first array element to get
* @param elements number of elements to get in the property
* @return byte array holding the retrieved element data
* @throws KNXException on adapter errors while querying the property element
* @throws InterruptedException on thread interrupt
*/
byte[] getProperty(int objIndex, int pid, int start, int elements)
throws KNXException, InterruptedException;
/**
* Gets one or more elements of a property with the returned data set in a DPT
* translator of the associated data type.
*
* @param objIndex interface object index in the device
* @param pid property identifier
* @param start index of the first array element to get
* @param elements number of elements to get in the property
* @return a DPT translator containing the returned the element data
* @throws KNXException on adapter errors while querying the property element or data
* type translation problems
* @throws InterruptedException on thread interrupt
*/
DPTXlator getPropertyTranslated(int objIndex, int pid, int start, int elements)
throws KNXException, InterruptedException;
/**
* Gets the property description based on the property ID.
*
* It is not always possible to supply all description information:
* If a description read is done using a property identifier (PID) like in this
* method, the description response is not required to contain the correct property
* index associated with the PID, even though recommended. The default index is 0
* then.
*
* @param objIndex interface object index in the device
* @param pid property identifier, pid > 0
* @return the property description
* @throws KNXException on adapter errors while querying the description
* @throws InterruptedException on thread interrupt
*/
Description getDescription(int objIndex, int pid) throws KNXException, InterruptedException;
/**
* Gets the property description based on the property index.
*
* @param objIndex interface object index in the device
* @param propIndex property index in the object, propIndex ≥ 0
* @return a property description object
* @throws KNXException on adapter errors while querying the description
* @throws InterruptedException on thread interrupt
*/
Description getDescriptionByIndex(int objIndex, int propIndex) throws KNXException,
InterruptedException;
}