tuwien.auto.calimero.dptxlator
Class DPTXlator3BitControlled

java.lang.Object
  extended by tuwien.auto.calimero.dptxlator.DPTXlator
      extended by tuwien.auto.calimero.dptxlator.DPTXlator3BitControlled

public class DPTXlator3BitControlled
extends DPTXlator

Translator for KNX DPTs with main number 3, type 3 Bit controlled.

The KNX data type width is 3 Bits, using the lowest 3 bits of 1 byte.
The type structure is [1 Bit control field][3 Bit stepcode field]. The default return value after creation is control flag set to false (0), stepcode 0 (break).

In value methods expecting string types, the item is composed of the corresponding subtype control field representation, followed by whitespace and the stepcode.
It might be formatted using decimal, hexadecimal, and octal numbers, distinguished by using these prefixes:

no prefix for decimal numeral
0x, 0X or # for hexadecimal
0 for octal numeral


Nested Class Summary
static class DPTXlator3BitControlled.DPT3BitControlled
          A DPT for the 3 Bit controlled, with additional access to the control information DPT.
 
Field Summary
static DPT DPT_CONTROL_BLINDS
          DPT ID 3.008, Blinds control; values are DPTXlatorBoolean.DPT_UPDOWN for control and 3 Bit stepcode.
static DPT DPT_CONTROL_DIMMING
          DPT ID 3.007, Dimming control; values are DPTXlatorBoolean.DPT_STEP for control and 3 Bit stepcode.
 
Fields inherited from class tuwien.auto.calimero.dptxlator.DPTXlator
appendUnit, data, dpt, LOG_SERVICE, logger, typeSize
 
Constructor Summary
DPTXlator3BitControlled(DPT dpt)
          Creates a translator for the given datapoint type.
DPTXlator3BitControlled(java.lang.String dptID)
          Creates a translator for the given datapoint type ID.
 
Method Summary
 java.lang.String[] getAllValues()
          Returns all translation items as strings currently contained in this translator.
 boolean getControlBit()
          Returns the control field of the first translation item.
 byte[] getData(byte[] dst, int offset)
          Copies KNX DPT value items stored by this translator into dst, starting at offset.
 byte getIntervals()
          Returns the number of intervals specified by the stepcode of the first translation item.
 byte getStepCode()
          Returns the stepcode of the first translation item.
 java.util.Map getSubTypes()
          Returns all available, implemented subtypes for the translator.
protected static java.util.Map getSubTypesStatic()
           
 byte getValueSigned()
          Returns the value of the first translation item, with the absolute value representing the stepcode, and the sign representing the control bit.
 void setControlBit(boolean value)
          Sets the control field to the specified direction for the first translation item.
 void setData(byte[] data, int offset)
          Sets the data array with KNX datapoint type items for translation.
 void setIntervals(int numberOfIntervals)
          Sets the stepcode of the first translation item to represent the given desired number of intervals.
 void setStepCode(int value)
          Sets the stop code for the first translation item.
 void setValue(boolean control, int stepcode)
          Sets one new translation item, replacing any old items.
 void setValue(int value)
          Sets one new translation item with the given signed value, replacing any old items.
protected  void toDPT(java.lang.String value, short[] dst, int index)
          Translates a string value representation into KNX data type according the current DPT and stores the result into dst.
 
Methods inherited from class tuwien.auto.calimero.dptxlator.DPTXlator
getData, getItems, getType, getTypeSize, getValue, setAppendUnit, setData, setTypeID, setValue, setValues, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DPT_CONTROL_BLINDS

public static final DPT DPT_CONTROL_BLINDS
DPT ID 3.008, Blinds control; values are DPTXlatorBoolean.DPT_UPDOWN for control and 3 Bit stepcode.


DPT_CONTROL_DIMMING

public static final DPT DPT_CONTROL_DIMMING
DPT ID 3.007, Dimming control; values are DPTXlatorBoolean.DPT_STEP for control and 3 Bit stepcode.

Constructor Detail

DPTXlator3BitControlled

public DPTXlator3BitControlled(DPT dpt)
                        throws KNXFormatException
Creates a translator for the given datapoint type.

Parameters:
dpt - the requested datapoint type
Throws:
KNXFormatException - on not supported or not available DPT

DPTXlator3BitControlled

public DPTXlator3BitControlled(java.lang.String dptID)
                        throws KNXFormatException
Creates a translator for the given datapoint type ID.

Parameters:
dptID - available implemented datapoint type ID
Throws:
KNXFormatException - on wrong formatted or not expected (available) dptID
Method Detail

getAllValues

public java.lang.String[] getAllValues()
Description copied from class: DPTXlator
Returns all translation items as strings currently contained in this translator.

The items are ordered the same way handed to the translator in the first place (FIFO, increasing byte index).

Specified by:
getAllValues in class DPTXlator
Returns:
an array of strings with values represented as strings
See Also:
DPTXlator.getValue()

getControlBit

public final boolean getControlBit()
Returns the control field of the first translation item.

A value of false stands for decrease / up, true for increase / down.

Returns:
control bit as boolean

getData

public byte[] getData(byte[] dst,
                      int offset)
Description copied from class: DPTXlator
Copies KNX DPT value items stored by this translator into dst, starting at offset.

The number of items copied depends on the usable dst range, i.e. how much items completely fit into dst.length - offset. If the usable range is too short, no item is copied at all, and dst is not modified.
Datapoint types shorter than 1 bytes only change the affected lower bit positions, leaving the upper (high) bits of dst bytes untouched.

Specified by:
getData in class DPTXlator
Parameters:
dst - byte array for storing DPT values
offset - offset into dst from where to start, 0 <= offset < dst.length
Returns:
dst

getIntervals

public final byte getIntervals()
Returns the number of intervals specified by the stepcode of the first translation item.

If a step break indication is set, the return value is 0.

Returns:
number of intervals in the range 1 <= intervals <= 64, or 0

getStepCode

public final byte getStepCode()
Returns the stepcode of the first translation item.

Returns:
stepcode value, 0 <= value <= 7
See Also:
getIntervals()

getSubTypes

public final java.util.Map getSubTypes()
Description copied from class: DPTXlator
Returns all available, implemented subtypes for the translator.

A subtype, identified through a sub number, specifies the available dimension, consisting of range and unit attributes. Together with the main type information this uniquely defines a datapoint type.
The datapoint type information is contained in a DPT object.

New or modified DPT information can be made available to the translator by adding entries to the map, likewise map entries might be removed. In other words, the map returned is the same used by the translators of one main type for DPT lookup. Changes to the map influence all translators of the same main type.
Changes of the DPT currently used by the translator take effect on the next new translator created using that DPT.
The map itself is not synchronized.

Specified by:
getSubTypes in class DPTXlator
Returns:
subtypes as Map, key is the subtype ID of type string, value of type DPT

getSubTypesStatic

protected static java.util.Map getSubTypesStatic()
Returns:
the subtypes of the 3 Bit controlled translator type
See Also:
DPTXlator.getSubTypesStatic()

getValueSigned

public final byte getValueSigned()
Returns the value of the first translation item, with the absolute value representing the stepcode, and the sign representing the control bit.

A positive control flag (true) is shown by a positive sign, a control flag of 0 (false) by a negative sign in the returned value.
In state "break" (stepcode 0), no distinction is made between control flag set / not set, both share the value 0.

Returns:
3 Bit controlled value as signed byte

setControlBit

public final void setControlBit(boolean value)
Sets the control field to the specified direction for the first translation item.

A value of false stands for decrease/up, true for increase/down.
This method does not reset other item data or discard other translation items.

Parameters:
value - control direction

setData

public void setData(byte[] data,
                    int offset)
Description copied from class: DPTXlator
Sets the data array with KNX datapoint type items for translation.

The data array contains at least one DPT item, the new item(s) will replace any other items set in the translator before.
The number of items (KNX data values) for translation in data is inferred from the length of the usable data range:
items = (data.length - offset) / (length of KNX data type)

In general, the KNX data type width is implicitly known in the context where a translator is invoked (e.g. by appropriate DP configuration), therefore data.length will satisfy the minimum acceptable length. If this is not the case, KNXIllegalArgumentException has to be caught and handled in the caller's context.

Specified by:
setData in class DPTXlator
Parameters:
data - byte array containing KNX DPT item(s)
offset - offset into data from where to start, 0 <= offset < data.length

setIntervals

public final void setIntervals(int numberOfIntervals)
Sets the stepcode of the first translation item to represent the given desired number of intervals.

This number specifies the intervals the range between 0 % and 100 % should get divided.
The value of numberOfIntervals is rounded to the nearest intervals representable with a stepcode. A mean value exact in between two intervals is rounded off (e.g 48 rounded of to 32, 3 rounded of to 2).
This method does not reset other item data or discard other translation items.

Parameters:
numberOfIntervals - desired intervals, 1 <= intervals <= 64

setStepCode

public final void setStepCode(int value)
Sets the stop code for the first translation item.

The stepcode is the encoded representation of the number of intervals. A stepcode of 0 is used for step break indication.
This method does not reset other item data or discard other translation items.

Parameters:
value - the stepcode, 0 <= value <= 7
See Also:
setIntervals(int)

setValue

public final void setValue(boolean control,
                           int stepcode)
Sets one new translation item, replacing any old items.

Parameters:
control - control direction
stepcode - the stepcode, 0 <= value <= 7
See Also:
setControlBit(boolean), setStepCode(int)

setValue

public final void setValue(int value)
Sets one new translation item with the given signed value, replacing any old items.

The value's absolute value represents the stepcode, and the sign represents the control flag, a positive control flag is shown by a positive sign, control flag 0 by a negative sign. A value of 0 is interpreted as stepcode 0 with positive control flag.

Parameters:
value - 3 Bit controlled value in signed representation
See Also:
getValueSigned()

toDPT

protected void toDPT(java.lang.String value,
                     short[] dst,
                     int index)
              throws KNXFormatException
Description copied from class: DPTXlator
Translates a string value representation into KNX data type according the current DPT and stores the result into dst. The index parameter specifies the item index of the value. The translated KNX data is stored at the corresponding array offset in dst. Calculation of offset: offset = index * KNX data type size.

Specified by:
toDPT in class DPTXlator
Parameters:
value - value to translate
dst - destination array for resulting KNX data
index - item index in destination array
Throws:
KNXFormatException - if value can't be translated due to wrong formatted content, or if valuedoesn't fit into KNX data type