Telemetry

```
public interface Telemetry
```
Instances of Telemetry provide a means by which data can be transmitted from the robot controller to the driver station and displayed on the driver station screen.
Simple use of Telemetry consists of a series of addData() calls, followed by a call to update(). For example:
```
     // LinearOpMode
     telemetry.addData("count", currentCount);
     telemetry.addData("elapsedTime", "%.3f", elapsedSeconds);
     telemetry.update();
 
```
In the 2015/16 season, the call to update() was not required; now, however, in a LinearOpMode, unless update() is called, nothing will appear on the driver station screen. In other, loop-based opmodes, update() continues to be called automatically at the end of OpMode.loop() and OpMode.init_loop(); no call to update() is required in loop-based opmodes.
```
     // loop-based opmode
     telemetry.addData("count", currentCount);
     telemetry.addData("elapsedTime", "%.3f", elapsedSeconds);
 
```
By default (but see setAutoClear()), data is cleared from the telemetry after each call to update(); thus, you need to issue addData() for the entire contents of the telemetry screen on each update cycle. This behavior is just as it was in the 2015/16 season.

A more complicated use of Telemetry might have different parts of the program update different items on the display in a decoupled, decentralized manner. Such situations might usefully avail themselves of turning off the auto-clear setting. For example:
```
     telemetry.setAutoClear(false);
     Telemetry.Item countItem = telemetry.addData("count", 0);
     Telemetry.Item elapsedItem = telemetry.addData("elapsedTime", 0);

     void onePartOfYourCode() {
         ...
         countItem.setValue(0);
         telemetry.update();
         ...
     }

     void anotherPartOfYourCode() {
         ...
         elapsedItem.setValue("%.3f", elapsedSeconds);
         telemetry.update();
         ...
     }
 
```
In this way different parts of the code can update only a portion of the telemetry screen without disturbing other parts.

Below the list of caption, value, pairs, on the screen a Telemetry also displays a short, unstructured log of messages. Use log().add() to add to the log. See also log().

Actual transmission to the driver station is throttled to avoid use of excessive bandwidth. By default, transmission will occur at most every 250ms. This interval can be controlled with setMsTransmissionInterval(). Any update()s which occur more frequently will not be transmitted if superseded by a subsequent update() before the transmission interval expires.

As mentioned above, by default, after each call to update(), the method clear() is automatically called. Thus, in simple usage, after each update(), you'll want to issue addData() calls to rebuild the entire driver station telemetry screen that you wish to observe. This simple usage can be modified in two ways.

First, the automatic issuance of calls to clear() can be altered by means of setAutoClear(boolean). If auto clearing is set to false, previously added telemetry items remain present from update() to update(), but their value can still be altered using Item.setValue(), items can be removed using removeItem(Item), and new items can be added using addData() and Item.addData().

Second, telemetry items created in a functional form using addData(String, Func) or Telemetry.Item.addData(String, Func) are not automatically removed when clear() is called, either implicitly or explicitly (though they are removed when clearAll() is called). The intent of such items is allow a one-time specification of telemetry items by providing a function that can produce a value to be displayed rather than providing the actual value itself. Such functions are evaluated only when it is known that telemetry is going to be transmitted to the driver station (and so a value is required). This approach can be particularly useful if the acquisition of the data to be displayed is relatively expensive or time consuming, as that cost is only expended when actually useful. In addition to one-item-per-line display on the driver station, multiple items per line can be displayed by starting with a call to addLine() and then following up with one or more addData(String, Object) calls. For example:
```
     telemetry.addLine()
          .addData("count", currentCount)
          .addData("elapsedTime", "%.3f", seconds);
     telemetry.addLine()
          .addData("voltage", "%.1f", getCurrentVoltage())
          .addData("orientation", "%s", getOrientation());
     telemetry.update();
 
```
Items on the same line are separated by the item separator. Caption and value within an item are separated by the caption value separator.

Note: in the 2015/16 season, it was possible for Telemetry instances to be automatically sorted in alphabetical order by caption. This functionality is no longer supported.

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`Telemetry.Item` Instances of `Telemetry.Item` represent an item of data on the drive station telemetry display.
`static interface`	`Telemetry.Line` Instances of `Telemetry.Line` build lines of data on the driver station telemetry display.
`static interface`	`Telemetry.Log` The `Telemetry.Log` in a `Telemetry` instance provides an append-only list of messages that appear on the driver station below the `Telemetry.Item`s of the `Telemetry`.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`java.lang.Object`	`addAction(java.lang.Runnable action)` In addition to items and lines, a telemetry may also contain a list of actions.
`<T> Telemetry.Item`	`addData(java.lang.String caption, Func<T> valueProducer)` Adds an item to the end of the telemetry being built for driver station display.
`Telemetry.Item`	`addData(java.lang.String caption, java.lang.Object value)` Adds an item to the end if the telemetry being built for driver station display.
`<T> Telemetry.Item`	`addData(java.lang.String caption, java.lang.String format, Func<T> valueProducer)` Adds an item to the end of the telemetry being built for driver station display.
`Telemetry.Item`	`addData(java.lang.String caption, java.lang.String format, java.lang.Object... args)` Adds an item to the end of the telemetry being built for driver station display.
`Telemetry.Line`	`addLine()` Creates and returns a new line in the receiver `Telemetry`.
`Telemetry.Line`	`addLine(java.lang.String lineCaption)` Creates and returns a new line in the receiver `Telemetry`.
`void`	`clear()` Removes all items from the receiver whose value is not to be retained.
`void`	`clearAll()` Removes all items, lines, and actions from the receiver
`java.lang.String`	`getCaptionValueSeparator()` Returns the string which is used to separate caption from value within a `Telemetry` `Telemetry.Item`.
`java.lang.String`	`getItemSeparator()` Returns the string which is used to separate `Telemetry.Item`s contained within a line.
`int`	`getMsTransmissionInterval()` Returns the minimum interval between `Telemetry` transmissions from the robot controller to the driver station
`boolean`	`isAutoClear()` Answers whether `clear()` is automatically called after each call to `update()`.
`Telemetry.Log`	`log()` Returns the log of this `Telemetry` to which log entries may be appended.
`boolean`	`removeAction(java.lang.Object token)` Removes a previously added action from the receiver.
`boolean`	`removeItem(Telemetry.Item item)` Removes an item from the receiver telemetry, if present.
`boolean`	`removeLine(Telemetry.Line line)` Removes a line from the receiver telemetry, if present.
`void`	`setAutoClear(boolean autoClear)` Sets whether `clear()` is automatically called after each call to `update()`.
`void`	`setCaptionValueSeparator(java.lang.String captionValueSeparator)`
`void`	`setItemSeparator(java.lang.String itemSeparator)`
`void`	`setMsTransmissionInterval(int msTransmissionInterval)` Sets the minimum interval between `Telemetry` transmissions from the robot controller to the driver station.
`boolean`	`update()` Sends the receiver `Telemetry` to the driver station if more than the `transmission interval` has elapsed since the last transmission, or schedules the transmission of the receiver should no subsequent `Telemetry` state be scheduled for transmission before the `transmission interval` expires.

- Method Detail
  - addData
```
Telemetry.Item addData(java.lang.String caption,
                       java.lang.String format,
                       java.lang.Object... args)
```
    Adds an item to the end of the telemetry being built for driver station display. The value shown will be the result of calling String.format() with the indicated format and arguments. The caption and value are shown on the driver station separated by the caption value separator. The item is removed if clear() or clearAll() is called.
    
    Parameters:
    
    caption - the caption to use
    
    format - the string by which the arguments are to be formatted
    
    args - the arguments to format
    
    Returns:
    
    an Telemetry.Item that can be used to update the value or append further Telemetry.Items
    
    See Also:
    
    addData(String, Object), addData(String, Func)
  - addData
```
Telemetry.Item addData(java.lang.String caption,
                       java.lang.Object value)
```
    Adds an item to the end if the telemetry being built for driver station display. The value shown will be the result of calling toString() on the provided value object. The caption and value are shown on the driver station separated by the caption value separator. The item is removed if clear() or clearAll() is called.
    
    Parameters:
    
    caption - the caption to use
    
    value - the value to display
    
    Returns:
    
    an Telemetry.Item that can be used to update the value or append further Telemetry.Items
    
    See Also:
    
    addData(String, String, Object...), addData(String, Func)
  - addData
```
<T> Telemetry.Item addData(java.lang.String caption,
                           Func<T> valueProducer)
```
    Adds an item to the end of the telemetry being built for driver station display. The value shown will be the result of calling toString() on the object which is returned from invoking valueProducer.Func.value() value()}. The caption and value are shown on the driver station separated by the caption value separator. The item is removed if clearAll() is called, but not if clear() is called.
    The valueProducer is evaluated only if actual transmission to the driver station is to occur. This is important, as it provides a means of displaying telemetry which is relatively expensive to evaluate while avoiding computation or delay on evaluations which won't be transmitted due to transmission interval throttling.
    
    Parameters:
    
    caption - the caption to use
    
    valueProducer - the object which will provide the value to display
    
    Returns:
    
    an Telemetry.Item that can be used to update the value or append further Telemetry.Items
    
    See Also:
    
    addData(String, String, Object...), addData(String, Object), addData(String, String, Func), getMsTransmissionInterval()
  - addData
```
<T> Telemetry.Item addData(java.lang.String caption,
                           java.lang.String format,
                           Func<T> valueProducer)
```
    Adds an item to the end of the telemetry being built for driver station display. The value shown will be the result of calling String.format(java.lang.String, java.lang.Object...) on the object which is returned from invoking valueProducer.Func.value() value()}. The caption and value are shown on the driver station separated by the caption value separator. The item is removed if clearAll() is called, but not if clear() is called.
    The valueProducer is evaluated only if actual transmission to the driver station is to occur. This is important, as it provides a means of displaying telemetry which is relatively expensive to evaluate while avoiding computation or delay on evaluations which won't be transmitted due to transmission interval throttling.
    
    Parameters:
    
    caption - the caption to use
    
    valueProducer - the object which will provide the value to display
    
    Returns:
    
    an Telemetry.Item that can be used to update the value or append further Telemetry.Items
    
    See Also:
    
    addData(String, String, Object...), addData(String, Object), addData(String, Func), getMsTransmissionInterval()
  - removeItem
```
boolean removeItem(Telemetry.Item item)
```
    Removes an item from the receiver telemetry, if present.
    
    Parameters:
    
    item - the item to remove
    
    Returns:
    
    true if any change was made to the receive (ie: the item was present); false otherwise
  - clear
```
void clear()
```
    Removes all items from the receiver whose value is not to be retained.
    
    See Also:
    
    Telemetry.Item.setRetained(Boolean), Telemetry.Item.isRetained(), clearAll(), addData(String, Func)
  - clearAll
```
void clearAll()
```
    Removes all items, lines, and actions from the receiver
    
    See Also:
    
    clear()
  - addAction
```
java.lang.Object addAction(java.lang.Runnable action)
```
    In addition to items and lines, a telemetry may also contain a list of actions. When the telemetry is to be updated, these actions are evaluated before the telemetry lines are composed just prior to transmission. A typical use of such actions is to initialize some state variable, parts of which are subsequently displayed in items. This can help avoid needless re-evaluation.
    Actions are cleared with clearAll(), and can be removed with removeAction().
    
    Parameters:
    
    action - the action to execute before composing the lines telemetry
    
    Returns:
    
    a token by which the action can be later removed.
    
    See Also:
    
    addData(String, Object), removeAction(Object), addLine(), update()
  - removeAction
```
boolean removeAction(java.lang.Object token)
```
    Removes a previously added action from the receiver.
    
    Parameters:
    
    token - the token previously returned from addAction().
    
    Returns:
    
    whether any change was made to the receiver
  - update
```
boolean update()
```
    Sends the receiver Telemetry to the driver station if more than the transmission interval has elapsed since the last transmission, or schedules the transmission of the receiver should no subsequent Telemetry state be scheduled for transmission before the transmission interval expires.
    
    Returns:
    
    whether a transmission to the driver station occurred or not
  - addLine
```
Telemetry.Line addLine()
```
    Creates and returns a new line in the receiver Telemetry.
    
    Returns:
    
    a new line in the receiver Telemetry
  - addLine
```
Telemetry.Line addLine(java.lang.String lineCaption)
```
    Creates and returns a new line in the receiver Telemetry.
    
    Parameters:
    
    lineCaption - the caption for the line
    
    Returns:
    
    a new line in the receiver Telemetry
  - removeLine
```
boolean removeLine(Telemetry.Line line)
```
    Removes a line from the receiver telemetry, if present.
    
    Parameters:
    
    line - the line to be removed
    
    Returns:
    
    whether any change was made to the receiver
  - isAutoClear
```
boolean isAutoClear()
```
    Answers whether clear() is automatically called after each call to update().
    
    Returns:
    
    whether clear() is automatically called after each call to update().
    
    See Also:
    
    setAutoClear(boolean)
  - setAutoClear
```
void setAutoClear(boolean autoClear)
```
    Sets whether clear() is automatically called after each call to update().
    
    Parameters:
    
    autoClear - if true, clear() is automatically called after each call to update().
  - getMsTransmissionInterval
```
int getMsTransmissionInterval()
```
    Returns the minimum interval between Telemetry transmissions from the robot controller to the driver station
    
    Returns:
    
    the minimum interval between Telemetry transmissions from the robot controller to the diver station
    
    See Also:
    
    setMsTransmissionInterval(int)
  - setMsTransmissionInterval
```
void setMsTransmissionInterval(int msTransmissionInterval)
```
    Sets the minimum interval between Telemetry transmissions from the robot controller to the driver station.
    
    Parameters:
    
    msTransmissionInterval - the minimum interval between Telemetry transmissions from the robot controller to the driver station
    
    See Also:
    
    getMsTransmissionInterval()
  - getItemSeparator
```
java.lang.String getItemSeparator()
```
    Returns the string which is used to separate Telemetry.Items contained within a line. The default separator is " | ".
    
    Returns:
    
    the string which is use to separate Telemetry.Items contained within a line.
    
    See Also:
    
    setItemSeparator(String), addLine()
  - setItemSeparator
```
void setItemSeparator(java.lang.String itemSeparator)
```
    See Also:
    
    setItemSeparator(String)
  - getCaptionValueSeparator
```
java.lang.String getCaptionValueSeparator()
```
    Returns the string which is used to separate caption from value within a Telemetry Telemetry.Item. The default separator is " : ";
    
    Returns:
    
    the string which is used to separate caption from value within a Telemetry Telemetry.Item.
  - setCaptionValueSeparator
```
void setCaptionValueSeparator(java.lang.String captionValueSeparator)
```
    See Also:
    
    getCaptionValueSeparator()
  - log
```
Telemetry.Log log()
```
    Returns the log of this Telemetry to which log entries may be appended.
    
    Returns:
    
    the log of this Telemetry to which log entries may be appended.
    
    See Also:
    
    addData(String, Object)

Interface Telemetry

Nested Class Summary

Method Summary

Method Detail

addData

addData

addData

addData

removeItem

clear

clearAll

addAction

removeAction

update

addLine

addLine

removeLine

isAutoClear

setAutoClear

getMsTransmissionInterval

setMsTransmissionInterval

getItemSeparator

setItemSeparator

getCaptionValueSeparator

setCaptionValueSeparator

log