tuwien.auto.calimero.tools.ProcComm

All Implemented Interfaces:: Runnable

public class ProcComm extends Object implements Runnable

A tool for Calimero providing KNX process communication.

ProcComm is a Runnable tool implementation allowing a user to read or write datapoint values in a KNX network. It supports KNX network access using a KNXnet/IP, KNX IP, USB, FT1.2, or TP-UART connection.

Group monitor mode:
When in group monitor mode, process communication lists group write, read, and read response commands issued on the KNX network. Datapoint values in monitored group commands are decoded for appropriate KNX datapoint types (DPT). In addition, a user can issue read and write commands on the terminal. Commands have the the following syntax: cmd datapoint [DPT] [value], with cmd = ("r"|"read") | ("w"|"write"). For example, r 1/0/3 will read the current value of datapoint 1/0/3. The command w 1/0/3 1.002 true will write the boolean value true for datapoint 1/0/3.
By default, this tool will show the decoded value of any matching datapoint type for received datapoint data. Issuing a read or write command and specifying a datapoint type (DPT) will override the default datapoint type translation behavior of this tool. For example, read 1/0/3 1.005 will decode subsequent values of that datapoint using the DPT 1.005 "Alarm" and its value representations "alarm" and "no alarm". A subsequent write can then simply issue w 1/0/3 alarm, setting datapoint 1/0/3 to "alarm" state.
When the tool exits and no user-supplied datapoints file was used, type information about any datapoint that was monitored is stored in a file on disk in the current working directory (if file creation/modification is permitted). That file is named something like ".proccomm_dplist.xml" (hidden file on Unix-based systems). It allows the tool to remember user-specific settings of datapoint types between tool invocations, important for the appropriate decoding of datapoint values. The file uses the layout of DatapointMap, and can be edited or used at any other place Calimero expects a DatapointModel. Note that any actual datapoint values are not stored in that file. Any user-supplied datapoints resource is not modified when the tool exits.

The tool implementation shows the necessary interaction with the Calimero-core library API for the described tasks. The main part of the implementation is based on the library's ProcessCommunicator, which offers high-level access for reading and writing process values. It also shows creation of a KNXNetworkLink, which is supplied to the process communicator, and serves as the link to the KNX network. For group monitoring, the tool uses Datapoint and DatapointModel to persist datapoints between tool invocations.

When running this tool from the terminal, method main of this class is invoked; otherwise, use this class in the context appropriate to a Runnable, or use start(ProcessListener) and quit().
In console mode, datapoint values as well as occurring problems are written to System.out.

Note that communication will use default settings if not specified otherwise using command line options. Since these settings might be system dependent (for example, the local host) and not always predictable, a user may want to specify particular settings using the available options.

Field Summary

Fields

Modifier and Type

Field

Description

protected tuwien.auto.calimero.process.ProcessCommunicator

pc

The used process communicator.
Constructor Summary

Constructors

Constructor

Description

ProcComm(String[] args)

Creates a new ProcComm instance using the supplied options.
Method Summary

Modifier and Type

Method

Description

protected String

asString(byte[] asdu, int dptMainNumber, String dptID)

Returns a string translation of the datapoint data for the specified datapoint type, using the process event ASDU.

protected String

decodeLteFrame(tuwien.auto.calimero.process.LteProcessEvent e)

protected void

issueCommand(String line)

Issues a read, write, or info command.

static void

main(String... args)

Entry point for running ProcComm.

protected void

onCompletion(Exception thrown, boolean canceled)

Called by this tool on completion.

protected void

onGroupEvent(tuwien.auto.calimero.process.ProcessEvent e)

Called by this tool on receiving a process communication group event.

protected void

onReadResponse(tuwien.auto.calimero.datapoint.Datapoint dp, String value)

If this tool instance is executing a read command, notifies about the read response (if any).

void

quit()

Quits process communication.

void

run()

void

start(tuwien.auto.calimero.process.ProcessListener l)

Starts the process communicator and returns.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- pc
  
  protected tuwien.auto.calimero.process.ProcessCommunicator pc
  
  The used process communicator.
Constructor Details
- ProcComm
  
  public ProcComm(String[] args)
  
  Creates a new ProcComm instance using the supplied options.
  Mandatory arguments are an IP host or a FT1.2 port identifier, depending on the type of connection to the KNX network. See main(String[]) for the list of options.
  
  Parameters:
  
  args - list with options
  
  Throws:
  
  tuwien.auto.calimero.KNXIllegalArgumentException - on unknown/invalid options
Method Details
- main
  
  public static void main(String... args)
  Entry point for running ProcComm. The endpoint for KNX network access is either an IP host or port identifier for IP, USB, FT1.2 or TP-UART communication. Use the command line option --help (or -h) to show the usage of this tool.
  Command line options are treated case sensitive. Available options for communication:
  
  --help -h show help message
  
  --version show tool/library version and exit
  
  --compact -c show incoming process communication data in compact format
  
  --localhost id local IP/host name
  
  --localport number local UDP port (default system assigned)
  
  --port -p number UDP port on host (default 3671)
  
  --nat -n enable Network Address Translation
  
  --ft12 -f use FT1.2 serial communication
  
  --usb -u use KNX USB communication
  
  --tpuart use TP-UART communication
  
  --medium -m id KNX medium [tp1|p110|knxip|rf] (defaults to tp1)
  
  --domain address domain address on open KNX medium (PL or RF)
  
  --sn number device serial number to use in RF multicasts & broadcasts
  
  --knx-address -k KNX address KNX device address of local endpoint
  
  The --knx-address option is only necessary if an access protocol is selected that directly communicates with the KNX network, i.e., KNX IP or TP-UART. The selected KNX individual address shall be unique in a network, and the subnetwork address (area and line) should be set to match the network configuration.
  Available commands for process communication:
  
  read group-address [DPT] read from datapoint with the specified group address, using DPT value format (optional)
  
  write group-address [DPT] value write to datapoint with the specified group address, using DPT value format
  
  monitor enter group monitoring
  
  In monitor mode, read/write commands can be issued on the terminal using cmd DP [DPT] [value], with cmd = ("r"|"read") | ("w"|"write").
  Additionally, the tool will either create or load an existing datapoint list and maintain it with all datapoints being read or written. Hence, once the datapoint type of a datapoint is known, the DPT part can be omitted from the command. The datapoint list is saved to the current working directory.
  Examples: write 1/0/1 switch off, w 1/0/1 off, r 1/0/1.
  For common datapoint types (DPTs) the following name aliases can be used instead of the general DPT number string:
  
  switch for DPT 1.001, with values off, on
  
  bool for DPT 1.002, with values false, true
  
  dimmer for DPT 3.007, with values decrease 0..7, increase 0..7
  
  blinds for DPT 3.008, with values up 0..7, down 0..7
  
  percent for DPT 5.001, with values 0..100
  
  % for DPT 5.001, with values 0..100
  
  angle for DPT 5.003, with values 0..360
  
  ucount for DPT 5.010, with values 0..255
  
  temp for DPT 9.001, with values -273..+670760
  
  float or float2 for DPT 9.002
  
  float4 for DPT 14.005
  
  int for DPT 13.001
  
  string for DPT 16.001
  Parameters:
  
  args - command line options for process communication
- run
  
  public void run()
  
  Specified by:
  
  run in interface Runnable
- start
  
  public void start(tuwien.auto.calimero.process.ProcessListener l) throws tuwien.auto.calimero.KNXException, InterruptedException
  
  Starts the process communicator and returns.
  This method immediately returns when this process communicator is already running. Call quit() to quit process communication. Restarting a process communicator is not supported.
  
  Parameters:
  
  l - a process event listener, can be null
  
  Throws:
  
  tuwien.auto.calimero.KNXException - on problems creating network link or communication
  
  InterruptedException - on interrupted thread
- quit
  
  public void quit()
  
  Quits process communication.
  Detaches the network link from the process communicator and closes the link.
- issueCommand
  
  protected void issueCommand(String line) throws tuwien.auto.calimero.KNXException, InterruptedException
  
  Issues a read, write, or info command.
  Parameters:
  
  line - line with command and arguments, e.g., "write 1/0/3 switch off"
  
  Throws:
  
  tuwien.auto.calimero.KNXException
  
  InterruptedException
  
  See Also:
  
  start(ProcessListener)
- onGroupEvent
  
  protected void onGroupEvent(tuwien.auto.calimero.process.ProcessEvent e)
  
  Called by this tool on receiving a process communication group event.
  
  Parameters:
  
  e - the process event
- onReadResponse
  
  protected void onReadResponse(tuwien.auto.calimero.datapoint.Datapoint dp, String value)
  
  If this tool instance is executing a read command, notifies about the read response (if any).
  
  Parameters:
  
  dp - datapoint
  
  value - formatted read response, or hexadecimal representation if dp has no DPT set
- onCompletion
  
  protected void onCompletion(Exception thrown, boolean canceled)
  
  Called by this tool on completion.
  
  Parameters:
  
  thrown - the thrown exception if operation completed due to a raised exception, null otherwise
  
  canceled - whether the operation got canceled before its planned end
- asString
  
  protected String asString(byte[] asdu, int dptMainNumber, String dptID) throws tuwien.auto.calimero.KNXException
  
  Returns a string translation of the datapoint data for the specified datapoint type, using the process event ASDU.
  
  Parameters:
  
  asdu - the process event ASDU with the datapoint data
  
  dptMainNumber - DPT main number ≥ 0, can be 0 if the dptID is unique
  
  dptID - datapoint type ID to lookup the translator
  
  Returns:
  
  the datapoint value
  
  Throws:
  
  tuwien.auto.calimero.KNXException - on failed creation of translator, or translator not available
- decodeLteFrame
  
  protected String decodeLteFrame(tuwien.auto.calimero.process.LteProcessEvent e) throws tuwien.auto.calimero.KNXFormatException
  
  Throws:
  
  tuwien.auto.calimero.KNXFormatException

Class ProcComm

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

pc

Constructor Details

ProcComm

Method Details

main

run

start

quit

issueCommand

onGroupEvent

onReadResponse

onCompletion

asString

decodeLteFrame