BLE RDK IR Service Specification
RDK-SP-BLE-RIR-Service-D01-200515
Document Status: Draft
May 15, 2020
Document Status

Document Status Codes
Work in Progress (W)An incomplete document designed to guide discussion and generate feedback that may include several alternative requirements for consideration.
Draft (D)A document in specification format considered largely complete, but lacking review. Drafts are susceptible to substantial change during the review process.
Issued (I)A stable document that has undergone rigorous review and is suitable for product design and development. It will serve as a basis for testing requirements.

Table of Contents
1. Introduction
1.1 Overview
1.2 Purpose of Document
1.3 Typographical Conventions
1.4 Requirements (Conformance Notation)
1.5 Revision History
2 References
2.1 Normative References
3 Terms and Definitions
4 Abbreviations and Acronyms
5 Introduction
5.1 Conformance
5.2 Service Dependency
5.3 Bluetooth Specification Release Compatibility
5.4 GATT Sub-Procedure Requirements
5.5 Transport Dependencies
5.6 Error Codes
5.7 Byte Transmission Order
6 Service Requirements
6.1 Service Declaration
6.2 Service Roles
6.3 Service Introduction
6.4 Service Sequence Examples
6.5 Characteristic Overview
6.6 IR Standby Configuration Characteristic
6.6.1 IR Standby Configuration Characteristic Behavior
6.6.2 IR Standby Configuration Characteristic Value
6.7 IR Code ID Characteristic
6.7.1 IR Code ID Characteristic Behaviour
6.7.2 IR Code ID Characteristic Value
6.8 IR Signal Characteristic
6.8.1 IR Signal Characteristic Behavior
6.8.2 IR Signal Characteristic Value
6.8.2.1 Large IR Signal Data Characteristic Values
6.8.3 IR Signal Characteristic Descriptors
6.8.3.1 IR Signal Reference Descriptors
6.8.3.2 IR Signal Configuration Descriptor
6.9 Emit IR Signal Characteristic
6.9.1 Emit IR Signal Characteristic Behavior
6.9.2 Emit IR Signal Characteristic Value

Tables
Table 1 - Typographical Conventions
Table 2 - Terms and Definitions
Table 3 - Abbreviations and Acronyms
Table 4 - GATT Sub-Procedure Requirement
Table 5 - Voice Service Characteristics
Table 6 - IR Standby Configuration Possible Values
Table 7 - IR Code ID Characteristic Values

Figures
Figure 1 - RDK IR Service

Anchor
_Toc236461453 _Toc236461453

Anchor
_Toc352579429 _Toc352579429

Anchor
_Toc40443670 _Toc40443670

Introduction

Anchor
_Toc236461454 _Toc236461454

Anchor
_Toc352579430 _Toc352579430

Anchor
_Toc40443671 _Toc40443671

Overview

Anchor
_Toc40443672 _Toc40443672

Purpose of Document

This document defines detailed requirements for the RDK IR Service. It is intended to specify download and management of IR descriptors between an RIR server and an RIR client.

Anchor
_Toc352579434 _Toc352579434

Anchor
_Toc40443673 _Toc40443673

Anchor
_Toc107845694 _Toc107845694

Anchor
_Toc107846682 _Toc107846682

Anchor
_Toc132173416 _Toc132173416

Anchor
_Toc153605725 _Toc153605725

Anchor
_Toc208903908 _Toc208903908

Typographical Conventions

This specification uses different typefaces to differentiate and emphasize important information.

Anchor
_Toc352579435 _Toc352579435

Anchor
_Toc40443674 _Toc40443674

Requirements (Conformance Notation)

Throughout this document, the words that are used to define the significance of particular requirements are capitalized. These words are:
"MUST"This word or the adjective "REQUIRED" means that the item is an absolute requirement of this specification document.
"MUST NOT"This phrase means that the item is an absolute prohibition of this specification document.
"SHOULD"This word or the adjective "RECOMMENDED" means that there may exist valid reasons in particular circumstances to ignore this item, but the full implications should be understood and the case carefully weighed before choosing a different course.
"SHOULD NOT"This phrase means that there may exist valid reasons in particular circumstances when the listed behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before choosing a different course.
"MAY"This word or the adjective "OPTIONAL" means that this item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because it enhances the product, for example; another vendor may omit the same item.

Anchor
_Toc40443675 _Toc40443675

Anchor
_Toc352579437 _Toc352579437

Revision History

Anchor
_Toc194472262 _Toc194472262

Anchor
_Toc194559202 _Toc194559202

Anchor
_Toc194559935 _Toc194559935

Anchor
_Toc216232400 _Toc216232400

Anchor
_Toc216236622 _Toc216236622

Anchor
_Toc220999718 _Toc220999718

Anchor
_Toc221949358 _Toc221949358

Anchor
_Toc352579438 _Toc352579438

Anchor
_Toc40443676 _Toc40443676

References

Reasonable effort is made to keep references up to date with respect to versions and release dates, however manufacturers are responsible for ensuring they have the most recent version of a reference specification (unless otherwise noted).
Where conflicts exist between requirements contained in this specification and normative references, the specification requirements govern.

Anchor
_Toc111007485 _Toc111007485

Anchor
_Toc111007732 _Toc111007732

Anchor
_Toc111007486 _Toc111007486

Anchor
_Toc111007733 _Toc111007733

Anchor
_Toc111007488 _Toc111007488

Anchor
_Toc111007735 _Toc111007735

Anchor
_Toc104019913 _Toc104019913

Anchor
_Ref95270381 _Ref95270381

Anchor
_Toc107845702 _Toc107845702

Anchor
_Toc107846690 _Toc107846690

Anchor
_Toc132173420 _Toc132173420

Anchor
_Toc153605729 _Toc153605729

Anchor
_Toc194472263 _Toc194472263

Anchor
_Toc194559203 _Toc194559203

Anchor
_Toc194559936 _Toc194559936

Anchor
_Toc216232401 _Toc216232401

Anchor
_Toc216236623 _Toc216236623

Anchor
_Toc220999719 _Toc220999719

Anchor
_Toc221949359 _Toc221949359

Anchor
_Toc352579439 _Toc352579439

Anchor
_Toc40443677 _Toc40443677

Normative References

 \[BLUETOOTH\] Bluetooth Core Specification version 4.0 or later 
\\

Anchor
_Toc352579442 _Toc352579442

Anchor
_Toc40443678 _Toc40443678

Terms and Definitions

This document uses the following terms and definitions.

Anchor
_Toc352579443 _Toc352579443

Anchor
_Toc40443679 _Toc40443679

Abbreviations and Acronyms

This document uses the following abbreviations and acronyms.

Anchor
_Toc40443680 _Toc40443680

Introduction

The RDK IR Service (RIS) exposes data and associated formatting for programming infrared signals into an RDK Remote Control Device or other device with an IR transmitter.

Anchor
_Toc40443681 _Toc40443681

Conformance

All capabilities indicated as mandatory for this Service shall be supported in the specified manner (process-mandatory). This also applies for all optional and conditional capabilities for which support is indicated.

Anchor
_Toc40443682 _Toc40443682

Service Dependency

This service is not dependent upon any other services.

Anchor
_Toc40443683 _Toc40443683

Bluetooth Specification Release Compatibility

This specification is compatible with any Bluetooth core specification\]\[BLUETOOTH\] referencesthat includes the Generic Attribute Profile (GATT) specification and the Bluetooth Low Energy Controller specification. 

Anchor
_Toc40443684 _Toc40443684

GATT Sub-Procedure Requirements

Requirements in this section represent a minimum set of requirements for an RDK Remote Control Device (GATT Server). Other GATT sub-procedures may be used if supported by both Client and Server.
Table 4 below summarises additional GATT sub-procedure requirements beyond those required by all GATT Servers.

Anchor
_Toc40443685 _Toc40443685

Transport Dependencies

The service shall only operate over an LE transport.

Anchor
_Toc40443686 _Toc40443686

Error Codes

This service does not define any application error codes that are used in Attribute Protocol.

Anchor
_Toc40443687 _Toc40443687

Byte Transmission Order

All characteristics used with this service shall be transmitted with the least significant octet first (i.e., little endian).

Anchor
_Toc40443688 _Toc40443688

Service Requirements

Anchor
_Toc11917225 _Toc11917225

Anchor
_Toc40443689 _Toc40443689

Service Declaration

The service UUID shall be set to:
TBD.

Anchor
_Toc11917226 _Toc11917226

Anchor
_Toc40443690 _Toc40443690

Service Roles

A remote control or similar low power device enabled with an IR transmitter should function as an RIS Server.
A settop box or other host capable of supplying IR data should function as an RIS Client.

Anchor
_Toc40443691 _Toc40443691

Service Introduction

Figure 1 depicts the characteristics and descriptors required of the service and the primary direction of data flow from / to the RDK STB host device.
RIS ServerRIS Client

Anchor
_Toc40443692 _Toc40443692

Service Sequence Examples

TBD

Anchor
_Toc40443693 _Toc40443693

Characteristic Overview

Anchor
_Toc40443694 _Toc40443694

IR Standby Configuration Characteristic

The IR Standby Configuration characteristic controls the behaviour of an RIR Client when the physical standby button is pressed and the RIR Client is not connected but is bonded to an RIR Server. The purpose is to control the events (IR and BLE) used to bring an RIR Server out of standby.
The UUID of the IR Standby Configuration characteristic is TBD.
A single instance of this characteristic shall exist as part of the RIR Service.

Anchor
_Toc40443695 _Toc40443695

IR Standby Configuration Characteristic Behavior

The IR Standby Configuration characteristic value can be read using the GATT Read Characteristic Value and is written using the GATT Write sub-procedure.

Anchor
_Toc40443696 _Toc40443696

IR Standby Configuration Characteristic Value

The characteristic contains a single octet, table 2.2 shows the allowed values.

This characteristic value shall be persistent across connections for bonded devices. The IR Standby Configuration characteristic is unique for each RIR Client. An RIR Client may read and write this descriptor to determine and set the configuration for that client.
The default value for the IR Standby Configuration characteristic is 0x00. Upon connection of non-bonded clients, this characteristic value is set to the default value.
If the RIR Server stores client information for multiple clients then it is the last connected client's value that shall be used to determine the standby key mode.

Anchor
_Toc40443697 _Toc40443697

IR Code ID Characteristic

The IR Code ID characteristic is used to expose the current IR code set id of the RIR IR Service with which it is associated, or to set the desired code set id of the Service. Unclear what this actually means
The UUID of the IR Code ID characteristic is TBD.
Only a single instance of this characteristic shall exist as part of the RIR Service.

Anchor
_Toc40443698 _Toc40443698

IR Code ID Characteristic Behaviour

Both IR code set id values are arbitrary signed 32-bit values that are written and read by the RIR Client. Their values shall not be interpreted or used by the RIR Server; the values shall be treated as opaque data.
The IR Code ID Characteristic value shall be maintained across power cycles and device bonding / un-bonding (i.e. the value should be stored in non-volatile memory and not linked to a bound client). The default shall be set to -1 by the service.

Anchor
_Toc40443699 _Toc40443699

IR Code ID Characteristic Value

The characteristic shall contain two 32-bit signed integer fields, one for the code set id of a TV and one for an AV amplifier.
Table 7 shows the data format of the characteristic value.

Table 2.3: Infrared Code ID characteristic value

Anchor
_Toc40443700 _Toc40443700

IR Signal Characteristic

The IR Signal characteristic is used to set the infrared signal data for a single physical button or function on an RIR Server.
The UUID of the Infrared Signal characteristic is TBD.
Multiple instances of this characteristic shall exist as part of the RIR Service. There shall be single instance of this characteristic for each physical button or function that supports infrared programming.

Anchor
_Toc40443701 _Toc40443701

IR Signal Characteristic Behavior

The IR Signal characteristic is used to store infrared format information such that the RIR Server can emit the given infrared signal when a physical button is pressed or an event happens.
Each characteristic shall have a single instance of the IR Signal Reference descriptor and a single instance of the IR Signal Configuration descriptor. The IR Signal Reference descriptor shall be used to identify which physical button the characteristic represents.

Anchor
_Toc40443702 _Toc40443702

IR Signal Characteristic Value

The Infrared Signal characteristic value shall be variable length octet array, it's format is outside of the scope of this document. It is expected that the RIR Client will receive an opaque blob of data from a vendor supplied infrared database. The complete blob of data will be written to this characteristic value.
On any Infrared Signal characteristic value write the enabled state of the characteristic shall be set to FALSE and a read of the Infrared Signal Configuration Descriptor shall indicate the signal is disabled.
The RIR Server will enable the signal with a write to the Infrared Signal Configuration Descriptor once it has completed the write to the Infrared Signal characteristic value. Figure 2.2 depicts the expected sequence for programming an infrared signal.

Anchor
_Toc40443703 _Toc40443703

Large IR Signal Data Characteristic Values

If writes of larger than ATT_MTU - 3 (20 octets) are required, then the device shall support Queued Writes as described in Bluetooth Core v4.0, Volume 3, Part F, Section 3.4.6.
If queued writes are used then the device shall support at least one buffer of a size large enough to store a single infrared signal blob. The RIR Server will guarantee that only one infrared signal characteristic is written at a time. A device may reject a queued write request if a queued write on another characteristic is in progress.

Anchor
_Toc40443704 _Toc40443704

IR Signal Characteristic Descriptors

Anchor
_Toc40443705 _Toc40443705

IR Signal Reference Descriptors

The Infrared Signal Reference characteristic descriptor is used to provide the physical button identifier for the Infrared Signal characteristic value.
The UUID of the Infrared Signal Reference descriptor is TBD.
The descriptor shall contain a single read only octet attribute. Table 2.2 shows the definition of the Infrared Signal Reference characteristic descriptor Attribute Value field.

Anchor
_Toc40443706 _Toc40443706

IR Signal Configuration Descriptor

The IR Signal Configuration characteristic descriptor is used to expose the signal enable / disable setting of the infrared signal.
The UUID of the Infrared Signal Configuration descriptor is TBD.
The descriptor shall contain a 1 octet readable and writeable attribute. Table 2.3 shows the definition of the Infrared Signal Configuration characteristic descriptor Attribute Value field.

The RIR Server may choose to not enable the given signal if it detects that the current Infrared Signal Characteristic value is invalid. In such cases a read of the attribute shall indicate the signal is still disabled.

Anchor
_Toc40443707 _Toc40443707

Emit IR Signal Characteristic

The Emit Infrared Signal characteristic is used to request that the service emit an infrared signal.
The UUID of the Emit Infrared Signal characteristic is TBD.
A single instance of this characteristic shall exist as part of the RIR Service.

Anchor
_Toc40443708 _Toc40443708

Emit IR Signal Characteristic Behavior

Either the GATT Write or GATT Write Without Response sub-procedure is used to write to the Emit Infrared Signal characteristic.
A write shall trigger an infrared signal to be emitted for a period of 200 milliseconds. If an infrared signal is programmed and enabled via the Infrared Control Point Characteristic then that shall be used for the signal. If an infrared signal is not programmed or disabled then the default infrared signal shall be emitted.
The signal shall be immediately stopped if another GATT write to this characteristic is received.
A GATT Read is optional, if implemented it shall return the current signal being emitted, this should only apply to signals being emitted that were triggered by a write to this characteristic (i.e. an infrared signal emitted in response to a physical button press shall not be indicated in the value read).

Anchor
_Toc40443709 _Toc40443709

Emit IR Signal Characteristic Value

The Emit Infrared Signal characteristic value is a single octet containing an enumeration of values as shown in Table 2.7.

A GATT write of 0xFF can be used to cancel a previous request to emit an infrared signal.