Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Device refactor for 2.0 #223

Open
wants to merge 2 commits into
base: next
Choose a base branch
from
Open

feat: Device refactor for 2.0 #223

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
abb2bf6
feat: Device first draft
jlacivita Jan 22, 2024
4d322ea
feat: Split Core & Extension APIs
jlacivita Feb 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
197 changes: 197 additions & 0 deletions requirements/specifications/device/device-information.md
View file
Open in desktop
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is meant by clear text, exactly? Human readable?

Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
# Device Information

Document Status: Working Draft

See [Firebolt Requirements Governance](../../governance.md) for more info.

| Contributor | Organization |
| --------------- | -------------- |
| Andrew Bennett | Sky |
| Piotr Kobzda | Liberty |
| Jeremy LaCivita | Comcast |
| Farhan Mahmood | Liberty |
| Jan Pedersen | Sky |

## 1. Overview
This document outlines the requirements for ontological, intrinsic, and product-related device indentification APIs.

**TODO**: add capabilities to all APIs

The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

## 2. Table of Contents
- [1. Overview](#1-overview)
- [2. Table of Contents](#2-table-of-contents)
- [3. Device Identifiers](#3-device-identifiers)
- [3.1. Device Identifier](#31-device-identifier)
- [3.2. Anonymized Device Identifier](#32-anonymized-device-identifier)
- [3.3. Device Name](#33-device-name)
- [4. Versions](#4-versions)
- [4.1. Platform Version](#41-platform-version)
- [4.2. Firmware Version](#42-firmware-version)
- [4.3. Debugging Info](#43-debugging-info)
- [5. Device Classification](#5-device-classification)
- [5.1. Type](#51-type)
- [5.2. Class](#52-class)
- [5.3. Make](#53-make)
- [5.4. Model](#54-model)
- [5.5. Serial Number](#55-serial-number)
- [6. Device Proposition](#6-device-proposition)
- [6.1. Distributor](#61-distributor)
- [6.2. Partner](#62-partner)
- [6.3. Propositions](#63-propositions)
- [7. Cuts](#7-cuts)
- [8. Refactored into to other modules](#8-refactored-into-to-other-modules)
- [8.1. MediaInfo](#81-mediainfo)
- [8.2. HDMI](#82-hdmi)
- [8.3. Network](#83-network)
- [8.4. Analog Output](#84-analog-output)
- [8.5. Manage SDK (TBD)](#85-manage-sdk-tbd)

## 3. Device Identifiers

### 3.1. Device Identifier
The Device module **MUST** expose a read-only, clear-text unique identifier of the device via the `Device.id` method.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the durability of this attribute? Does it survive device reset? Is it available even on a new device?


This API will likely only be permitted to fisrt-party apps and **MUST** only be surfaced in the Manage SDK.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fisrt - typo


The value of this **MUST** be unique within a distributor.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or is the scope implementation defined?


This API requires `use` access to the `xrn:firebolt:capability:device:identification` capability.

**NOTE**: we probably need a registry of Firebolt distributors to avoid collisions.

### 3.2. Anonymized Device Identifier
The Device module **MUST** expose a read-only, anonymized device identifier that is consistent across launches of the same app via the `Device.uid` method.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is meant by anonymized here?


The value of this **MUST** be unique within a distributor and per app.

The anonymized device identifier **MUST NOT** be trackable across apps.

The anonymized device identifiers **MUST** be resettable for all apps at once via the `Device.resetIdentifiers()` method.

The anonymized device identifier **MUST** be an MD5 hash of:

- `Device.distributor()`
- `Device.id()`
- curent app id
- the timestamp of when `Device.resetIdentifiers()` was last called, or the Epoch

**TODO**: What is the use case? if it's just Advertising, then we should cut this.
**NOTE**: Potentially connected to user opts out of personalized recommendations

### 3.3. Device Name
The Device module **MUST** expose a read/write/notification property of the user preferred name of the device via the `Device.name` method.

## 4. Versions

### 4.1. Platform Version
The Device module **MUST** expose the highest supported Firebolt API version as a `SemanticVersion` object via the `Device.version()` method.

A `SemanticVersion` is structured as follows:

```typescript
type SemanticVersion = {
major: number;
minor: number;
patch: number;
readable: string;
}
```

**NOTE**: The SDK version is moved to a statically generated `SDK.version` method and does not involve an RPC call:

```typescript
import { SDK } from '@firebolt-js/sdk'

console.log(SDK.version())
```

### 4.2. Firmware Version
The Device module **MUST** expose the current firmware version as a `string` via the `Device.firmware()` method.

### 4.3. Debugging Info
The Device module **MUST** expose a free-form debugging `string` via the `Device.debugInfo()` method.

## 5. Device Classification

### 5.1. Type
The Device module **MUST** expose the read-only type of device, e.g. IPSTB, via the `Device.type` method.

The `type` method **MUST** return one of:

- `STB`
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this match the Comcast/Sky Ontology?

- `TV`

### 5.2. Class
Some sort of `string` hardware vendor profiling of the device, e.g. QUALM vs IP... need more examples

- `QUALM``
- `IP`

### 5.3. Make
The Device module **MUST** expose the read-only manufacturer of the device, e.g. "Raspberry Pi, ltd", via the `Device.make` method.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

String is implementation defined, e.g. a serialized string on EntOS devices.

**NOTE**: Definitely NOT an enum, but, do we want this value to be consistent across distributors? Do we need a registry?

### 5.4. Model
The Device module **MUST** expose the model number of the device, e.g. "Raspberry Pi 400", via the `Device.model` method.

The Device model **SHOULD NOT** include the make.

### 5.5. Serial Number
The Device module **MUST** expose the read-only serial number of the device via the `Device.serialNumber` method.

This API will likely only be permitted to fisrt-party apps and **MUST** only be surfaced in the Manage SDK.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fisrt - typo


The value of this **MUST** be unique within a make and model, even across distributors.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm... I would say that this is also implementation defined


## 6. Device Proposition

### 6.1. Distributor
The Device module **MUST** expose the read-only distributor of the device, e.g. "RDK Management" via the `Device.distributor` method.

**NOTE**: we probably need a registry of Firebolt distributors to avoid collisions.
**TODO**: Confirm RDK-M distributor name.

### 6.2. Partner
The Device module **MUST** expose the read-only distribution partner of the device, e.g. "RDK Demos".
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The is the partner id from the ontology?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The partner may not be known - presumably return an empty string?


The distribution partner is a way to have one or more sub-divisions within a distributor.

### 6.3. Propositions
The Device module **MUST** expose a list of product propositions that are currently enabled or that the device is currently entitled to surface.

**TODO**: need examples.

## 7. Cuts

- Device.sku
- Device.platform

## 8. Refactored into to other modules
**NOTE**: this section will go away once reviewed.

### 8.1. MediaInfo

- Device.audio
- Device.hdr
- Device.screenResolution
- Device.videoResolution

### 8.2. HDMI

- Device.hdcp

### 8.3. Network

- Device.network

### 8.4. Analog Output

- TBD...

### 8.5. Manage SDK (TBD)

- Device.provision

109 changes: 109 additions & 0 deletions requirements/specifications/device/syndication-ontology.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
# Syndication SDK

Document Status: Working Draft

See [Firebolt Requirements Governance](../../governance.md) for more info.

| Contributor | Organization |
| --------------- | -------------- |
| Jeremy LaCivita | Comcast |
| Peter Yu | Comcast |

## 1. Overview
This document outlines the requirements for ontological, intrinsic, and product-related device indentification APIs.

**TODO**: add capabilities to all APIs

The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

## 2. Table of Contents
- [1. Overview](#1-overview)
- [2. Table of Contents](#2-table-of-contents)
- [3. Ontology](#3-ontology)
- [3.1. OS Class](#31-os-class)
- [3.2. Leased](#32-leased)
- [3.3. Experience](#33-experience)
- [3.4. Account Type](#34-account-type)
- [3.5. Account Sub Type](#35-account-sub-type)
- [3.6. Programmer](#36-programmer)
- [3.7. Retailer](#37-retailer)

## 3. Ontology
The Syndication Extension SDK **MUST** expose an `Ontology` module to contain the APIs outlined below.

### 3.1. OS Class
The `Ontology` module of the Syndication Extension SDK **MUST** have a string `osClass` property that returns what software and bootstrap configuration needs to be loaded on the device for a given operator.

This property **MUST** be readable by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability.

This property **MUST** be read/write and have a setter available to any app with `manage` access to the `xrn:firebolt:capability:syndication:ontology` capability.

The value **SHOULD** be set during device activation by a 1st party setup experience.

Examples values:

- `entos-rdk-residential`
- `entos-rdk-commercial`
- `skyq-rdk`
- `xre-rdk`
- `flex-rdk`

### 3.2. Leased
The `Ontology` module of the Syndication Extension SDK **MUST** have a boolean `leased` property that returns whether or not the device is leased by the customer (true) or owned (false).

This property **MUST** be readable by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability.

This property **MUST** be read/write and have a setter available to any app with `manage` access to the `xrn:firebolt:capability:syndication:ontology` capability.

The value **SHOULD** be set during device activation by a 1st party setup experience.

### 3.3. Experience
The `Ontology` module of the Syndication Extension SDK **MUST** have a string `experienceAppId` property that returns the appId of the primary aggregated experience app, aka "launcher", aka EPG, installed on this device.

This property **MUST** be readable by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability.

This property **MUST** be read/write and have a setter available to any app with `manage` access to the `xrn:firebolt:capability:syndication:ontology` capability.

The value **SHOULD** be set during device activation by a 1st party setup experience.

**TODO**: is app id okay here? what if a Firebolt app is using this API and is running on a different distribution platform w/ different app ids?

### 3.4. Account Type
The `Ontology` module of the Syndication Extension SDK **MUST** have a string `accountType` property that returns the type of account that is active on this device, e.g. `"residential"` or `"business"`.

This property **MUST** be read only by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability.

The value of this property **MUST** be configurable as a pass-through provider and may be provided by an App, a middleware component, or a cloud REST API.

See [Cloud Pass-through Providers](#) for more info.

### 3.5. Account Sub Type
The `Ontology` module of the Syndication Extension SDK **MUST** have a string `accountSubType` property that returns the type of account that is active on this device, e.g. `"hospitality"` or `"university"`.

This property **MUST** be read only by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability.

The value of this property **MUST** be configurable as a pass-through provider and may be provided by an App, a middleware component, or a cloud REST API.

See [Cloud Pass-through Providers](#) for more info.

### 3.6. Programmer
The `Ontology` module of the Syndication Extension SDK **MUST** have a string `programmerId` property that returns the ID of the partner that is providing programming to the primary aggregated experience.

This property **MUST** be readable by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability.

This property **MUST** be read/write and have a setter available to any app with `manage` access to the `xrn:firebolt:capability:syndication:ontology` capability.

The value **SHOULD** be set during device activation by a 1st party setup experience.

**TODO**: What is the scope of these ids?

### 3.7. Retailer
The `Ontology` module of the Syndication Extension SDK **MUST** have a string `retailerId` property that returns the ID of the partner that initially retailed the device.

This property **MUST** be readable by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability.

This property **MUST** be read/write and have a setter available to any app with `manage` access to the `xrn:firebolt:capability:syndication:ontology` capability.

The value **SHOULD** be set during device activation by a 1st party setup experience.

**TODO**: What is the scope of these ids?
Loading