Skip to content

Commit

Permalink
Merge pull request #1 from AMWA-TV/publish-CR
Browse files Browse the repository at this point in the history
Initial content
  • Loading branch information
cristian-recoseanu authored Jan 16, 2024
2 parents 6c30be6 + 98f9774 commit 17be473
Show file tree
Hide file tree
Showing 18 changed files with 365 additions and 10 deletions.
35 changes: 35 additions & 0 deletions APIs/schemas/invoke-method.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "PATCH request body for invoking a method",
"title": "Invoke method body",
"required": [
"methodId"
],
"properties": {
"methodId": {
"type": "object",
"description": "ID structure for the target method",
"required": [
"level",
"index"
],
"properties": {
"level": {
"type": "integer",
"description": "Level component of the method ID",
"minimum": 1
},
"index": {
"type": "integer",
"description": "Index component of the method ID",
"minimum": 1
}
}
},
"arguments": {
"type": "object",
"description": "Method arguments. Arguments are specified as nested properties inside this object and their types are dictated by the specific MS-05-02 model for the method targeted. Arguments only need to be included for methods which have arguments and MUST be omitted if the method does not require any arguments."
}
}
}
37 changes: 37 additions & 0 deletions APIs/schemas/modify-property.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "PUT request body for modyfing a property",
"title": "Modify property body",
"required": [
"value"
],
"properties": {
"value": {
"description": "New property value. The actual type is determined by the property's MS-05-02 datatype.",
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "object"
},
{
"type": "array"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
}
}
}
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ This repository holds the source for this Specification, part of the family of [

### What does it do?

- x
Describes the specification for the NMOS Configuration API.

### Why does it matter?

- x
Sets out the rules and requirements for implementing the NMOS Device Configuration API in devices and controllers.

### How does it work?

- x
Describes a standard way of exposing [MS-05-02](https://specs.amwa.tv/ms-05-02/) models when using an HTTP API.

<!-- INTRO-END -->

Expand Down
194 changes: 194 additions & 0 deletions docs/API requests.md

Large diffs are not rendered by default.

20 changes: 20 additions & 0 deletions docs/Data type marshalling.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Data type marshalling

| Type | JSON representation |
| ---------------------------- | ---------------------------------------- |
| enums | Integer associated enum value |
| NcString | string |
| NcBoolean | boolean |
| NcInt16 | number |
| NcInt32 | number |
| NcInt64 | number |
| NcUint16 | number (must be unsigned) |
| NcUint32 | number (must be unsigned) |
| NcUint64 | number (must be unsigned) |
| NcFloat32 | number (must be floating point) |
| NcFloat64 | number (must be floating point) |
| struct types | object |
| sequences of primitive types | array of primitive types |
| sequences of struct types | array of objects |

For specific datatype definitions consult the [NMOS Control Framework](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#datatypes).
2 changes: 2 additions & 0 deletions docs/Getting block members.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Getting block members

40 changes: 40 additions & 0 deletions docs/IS-04 interactions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# IS-04 interactions

The API availability MUST be advertised through existing IS-04 practices inside the controls array of an NMOS Device. Devices MUST include the `urn:x-nmos:control:configuration` control type.

```json
{
...
"senders": [
"a65c15a4-a52e-4960-8cd2-e05c31196e5f",
"68f519a3-5523-4b2c-b72d-ec23cc80207d"
],
"receivers": [
"8a7bb1c1-4a82-4fd9-a4fb-96f68f560831",
"ab450c07-ce54-44da-9ea9-c3e62e7b06d0"
],
"controls": [
{
"type": "urn:x-nmos:control:configuration/v1.0",
"href": "http://192.168.10.3/x-nmos/configuration/v1.0/"
}
],
"tags": {},
"type": "urn:x-nmos:device:generic",
"label": "NMOS Device",
"version": "1529676926:000000000",
"node_id": "d1713110-7343-4d9e-b3f4-456c8f6ce765",
"id": "58f6b536-ca4c-43fd-880a-9df2501fc125",
"description": "NMOS Device"
...
}
```

A given instance of the Configuration API MAY offer control of multiple Devices in a Node from a single URI. Alternatively there MAY be multiple instances of the API on one Node, for example, each corresponding to one Device.
In either case, the ‘control’ endpoint for each Device’s Configuration API instance MUST be advertised, even if the URI is the same.

This flexibility is to accommodate different relationships between Devices and Nodes. For example, some Devices may be loosely coupled to the Node, for example cards in a card frame.
These Devices are more likely to have an instance of the API for each card.
Others may be tightly coupled, for example a media processing pipeline on a server, where it is likely to be preferable to have one instance of the API that is advertised for each pipeline.

`TODO`: decide on `href` format and trailing slashes
12 changes: 6 additions & 6 deletions docs/Overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,14 @@ _(c) AMWA 2023, CC Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)_

## Introduction

> Provide an overview of the Specification.
This document aims to give a general description of the NMOS Device Configuration API. This API defines how NMOS Control models (described in the NMOS Control Framework) can be exposed and consumed in a standardized way when using HTTP.

Familiarity with the [JT-NM Reference Architecture](https://jt-nm.org/reference-architecture/) is assumed.
This document relies on previous familiarity with the following existing documents:

See also the [NMOS Technical Overview](https://specs.amwa.tv/nmos/main/docs/Technical_Overview.html).
* [AMWA MS-05-01 NMOS Control Architecture](https://specs.amwa.tv/ms-05-01)
* [AMWA MS-05-02 NMOS Control Framework](https://specs.amwa.tv/ms-05-02)

This API does not support subscriptions and notifications. For subscriptions and notifications support see [AMWA IS-12](https://specs.amwa.tv/is-12/).

## Use of Normative Language

Expand All @@ -24,9 +26,7 @@ and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119]

## Definitions

The NMOS terms 'Node', ... are used as defined in the [NMOS Glossary](https://specs.amwa.tv/nmos/main/docs/Glossary.html).

> List as appropriate
The NMOS term 'Device' is used as defined in the [NMOS Glossary](https://specs.amwa.tv/nmos/main/docs/Glossary.html).

This specification also defines the following terms.

Expand Down
12 changes: 12 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
### Introduction

- [Overview](Overview.md)

### Specification

- [Transport and message encoding](Transport%20and%20message%20encoding.md)
- [Security and authorization](Security%20and%20authorization.md)
- [API requests](API%20requests.md)
- [Data type marshalling](Data%20type%20marshalling.md)
- [IS-04 interactions](IS-04%20interactions.md)

### Examples

- [Getting block members](Getting%20block%20members.md)
10 changes: 10 additions & 0 deletions docs/Security and authorization.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Security and authorization

Authorization and transport security features described in the BCP-03-XX suite and in IS-10 are used to secure and authorize this protocol.

The relevant documents can be found here:

- [AMWA BCP-003-01 Secure Communication in NMOS Systems](https://specs.amwa.tv/bcp-003-01)
- [AMWA BCP-003-02 Authorization in NMOS Systems](https://specs.amwa.tv/bcp-003-02)
- [AMWA BCP-003-03 Certificate Provisioning in NMOS Systems](https://specs.amwa.tv/bcp-003-03)
- [AMWA IS-10 NMOS Authorization Specification](https://specs.amwa.tv/is-10)
5 changes: 5 additions & 0 deletions docs/Transport and message encoding.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Transport and message encoding

Implementations MUST use `HTTP` as the communication transport.

Implementations MUST use `JSON` as the message encoding data format.
Binary file added docs/images/getting-a-property.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/getting-block-members.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/getting-class-descriptor.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/getting-datatype-descriptor.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/invoking-a-method.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/putting-a-property.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion spec.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,4 @@ alt_repo_name: nmos-device-configuration
repo_url: https://github.com/AMWA-TV/is-14
releases:
default_branch: v1.0-dev
show_in_index: false
show_in_index: true

0 comments on commit 17be473

Please sign in to comment.