Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

RemoTI-1.4.0 Migration Guide

From Texas Instruments Wiki
Jump to: navigation, search

This page intends to highlight what needs to be considered when moving from RemoTI-1.3.1 to RemoTI-1.4.0. Features that are new in RemoTI-1.4.0, and does not have an equivalent in RemoTI-1.3.1 are not described here. Please refer to Advanced Remote User's Guide and RemoTI Developer's Guide for details about those features.

For a full comprehension of the differences between the two installers it is recommended to look at the differences using a GUI (e.g. Beyond Compare or meld). Most folders and even source files have not been renamed, so it is quite easy to use a tool to check the differences. The only notable difference, that could complicate using a tool, is that the driver code for the Advanced Remote target folder has been renamed from CC2533ARC_RTM to CC2533ARC.

Configuration

This section discusses what has changed regarding configuration.

Just like for RemoTI-1.3.1 most of the configuration is performed before calling RemoTI_InitReq(). Some information is requested by the stack post initialization when required.

Note that unlike RTI items, these new items are not stored in NV, so they must be set before every call to RTI_InitReq(), typically during boot/initialization. This makes more sense since the initialization routine for most implementations are run on every boot and as such already exist as part of program code. This especially true for single chip systems where the same boot code, including configuration, is run on every boot.

To support ZRC2.0 the profile ID 0x03 must be added to the profile ID list. The other existing configuration items remain unchanged. There are however a few new configuration items, see the following table.

Item Item description Mandatory/ Optional Set before RTI_InitReq()
0x81 GDP_ITEM_GDP_CAPABILITIES Defines what GDP functionality to support.
  • Extended Validation
  • Poll Server
  • Poll Client
  • Identification Server
  • Identification Client
  • Enhanced Security
  • Shared Secret Local
  • Shared Secret Remote
M x
0x82 GDP_ITEM_KEY_EX_TRANSFER_COUNT Defines the number of key seeds to use during key seeds exchanged, during the security phase of the pairing. The stack will set it to its default of 3 if not defined. O x
0x83 GDP_ITEM_POWER_STATUS Defines the current power status. O
0x86 GDP_ITEM_MAX_BINDING_CANDIDATES Defines the maximum number of binding candidates. It's not necessary to set this attribute as it is controlled by the compilation of the NWK library. O
0x87 GDP_ITEM_AUTO_CHECK_VALIDATION_PERIOD During the validation phase the Binding Originator polls the Binding Recipient for validation status. This happens at regular intervals defined by the attribute aplAutoCheckValidationPeriod. Configure this if the node is a Recipient node. M* x
0x8A GDP_ITEM_LINK_LOST_WAIT_TIME aplLinkLostWaitTime attribute defines how long the validation check polls can be missing before the link is deemed lost. Configure this if the node is a Recipient node. M* x
0x8B GDP_ITEM_IDENTIFICATION_CAPABILITIES Defines what is supported for client notifications. Should be configured if Poll Client is declared as supported in the GDP capabilities, and the intention with the Poll Client is to receive notifications.
  • Stop On Action
  • Flash Light
  • Short Sound
  • Vibrate
O* x
0xA1 ZRC_ITEM_ZRC_PROFILE_CAPABILITIES Defines what ZRC functionality to support.
  • Actions Originator
  • Actions Recipient
  • Home Automation Originator
  • Home Automation Recipient
  • Action Mapping Client
  • Action Mapping Server
  • Vendor Specific IR Data Base Formats
  • Inform About Supported Actions
M x
0xA4 ZRC_ITEM_ACTION_BANKS_SUPPORTED_RX 256 bits long bitmask to list all action banks that are supported in Rx. Must be configured if Actions Recipient support is listed as ZRC2.0 capability. For each action bank supported a corresponding Action Codes bitmask must be available when the profile layer requests it during the configuration phase. Application must implement the function RTI_GetAttributeReq() to support this. See RemoTI Linux ZRC2.0 Host - Configuration O* x
0xA5 ZRC_ITEM_ACTION_BANKS_SUPPORTED_TX 256 bits long bitmask to list all action banks that are supported in Tx. Must be configured if Actions Originator support is listed as ZRC2.0 capability. For each action bank supported a corresponding Action Codes bitmask must be available when the profile layer requests it during the configuration phase. Application must implement the function RTI_GetAttributeReq() to support this. O* x
  • M* - Mandatory, but default value exist, so it does not necessarily have to be configured
  • O* - Mandatory if configured to support feature. One must for example provide Rx Action Banks list if Action Banks Rx are declared as supported in ZRC2.0 capabilites.

Pairing/Binding

This section discusses what has changed regarding pairing/binding.

RemoTI-1.3.1 supports ZRC1.1 and ZID. Both these profiles are based on "push-button" pairing. RemoTI-1.4.0 supports ZRC2.0 which implements a more comprehensive pairing protocol. This protocol is backwards compatible with the "push-button" pairing of ZRC1.1 and ZID profiles. Note that this does not extend to the configuration phase of ZID which is required to pair using ZID.

The following table lists the APIs for RemoTI-1.3.1 and their equivalent API for RemoTI-1.4.0

RemoTI-1.3.1 API RemoTI-1.4.0 Comments
Controller/Originator
RTI_PairReq() RTI_BindReq() Initiates a pairing/binding request
RTI_StartValidationInd() Profile layer notifies application that the validation phase has started. Application must now act on user input to generate validation data and send via RTI_SendDataReq()
RTI_PairCnf() RTI_BindCnf() Confirmation of a binding attempt
RTI_PairAbortReq() RTI_BindAbortReq() Aborts an ongoing pairing/binding request
Target/Recipient
RTI_AllowPairReq() RTI_AllowBindReq() For a Recipient/Target node this tells the profile layer to accept pairing attempts according to the "push-button" pairing protocol.
RTI_StartValidationReq() Profile layer notifies the application that the validation phase for a binding has started.
RTI_GetValidationStatusInd() Profile layer requests the application about the validation status, upon request from the Binding Originator. Application must respond with RTI_GetValidationStatusRsp()
RTI_AllowPairCnf() RTI_BindInd() Profile layer notifies the application about the status of a binding attempt upon completion.
RTI_AllowPairAbortReq() RTI_AllowBindAbortReq() For a Recipient/Target node this tells the profile layer to abort accepting pairing attempts according to the "push-button" pairing protocol.

Data Formatting

This section discusses what has changed regarding data formatting.

RemoTI-1.3.1 supports ZRC1.1 and ZID profiles, while RemoTI-1.4.0 supports ZRC2.0. Since ZRC2.0 absorbs the functionality of the ZID, RemoTI-1.4.0 focus on how to move the HID data, that used to be wrapped in ZID data frames, in ZRC Actions. An action can be anything, including a simple key press.

ZRC1.1 HDMI-CEC

In ZRC1.1 the main data that is sent over the air is HDMI-CEC data commands. In ZRC2.0 these commands are a subset of all the data that can be transmitted. Whereas ZRC1.1 had a very simple, 2 byte, data payload which just indicated state and data of the keypress, ZRC2.0 is designed to convey actions.

ZID HID

In ZID HID reports are sent over the air as part of report records. In ZRC2.0 HID reports are not sent, but individual HID Usage IDs can be sent. Unfortunately there are no easy way to send HID Mouse data via Usage ID. To simplify the transition from ZID to ZRC2.0, and to be able to send HID Mouse reports, RemoTI-1.4.0 defines a vendor defined action bank with a single action. Within this action we transmit the HID reports, including report ID, as they were sent inside the ZID report record.

HID Keyboard
ZID Report Record (Keyboard Report)
Number of bytes 1 1 1 1 1 1 6
Field (space for alignment only) ZID Header HID Report
Sub-Field cmd len type id mods reserved key array
ZRC2.0 TI Vendor Specific Action (Keyboard Report)
Number of bytes 1 1 1 1 1 2 1 1 1 1 1 6
Field ZRC Header HID Report
Sub-Field hdr control len bank code vendorId vendor payload (ZID Record incl HID Keyboard Report)
len type id mods reserved key array
HID Mouse
ZID Report Record (Mouse Report)
Number of bytes 1 1 1 1 1 1 1
Field (space for alignment only) ZID Header HID Report
Sub-Field cmd len type id buttons x y
ZRC2.0 TI Vendor Specific Action (Mouse Report)
Number of bytes 1 1 1 1 1 2 1 1 1 1 1 1
Field ZRC Header HID Report
Sub-Field hdr control len bank code vendorId vendor payload (ZID Record incl HID Keyboard Report)
len type id buttons x y