About RCI descriptors

An ongoing problem consumers of RCI have is that although RCI specifies a format for requests and replies, it does not mandate a complete command set nor does it dictate what is allowed to be configured via RCI; for example, whether a device allows configuration of IP passthrough.

These limitations result in knowledge needing to be built into RCI clients about specific RCI targets, including firmware version-by-version differences, product-by-product differences, and so on. RCI also does not specify firmware version explicitly, so every client must know about every possible RCI target type and specific target variations.

Some observed problems with the current RCI implementation include:

RCI clients must be manually kept up to date with changes to RCI targets. If RCI targets change frequently, the RCI client must change very frequently or will become out-of-date and progressively less useful. This is exactly what has happened with the legacy Remote Manager management interface with respect to configuring NDS based devices.
Documentation must be manually generated that attempts to document the features of RCI targets. This is a very manual, intensive process, resulting in infrequent updates; as a result, documentation tends to be extremely out of date. This results in a significant mismatch between what users see in a device and what the documentation covers. Users must rely on the documentation since there is no other way for them to use RCI, resulting in a very poor user experience.
Testability is lacking. Thorough testing of RCI is essentially not possible currently, since a tester would need to inspect all of RCI and settings implementation to figure out what has changed. Such testing is not practical.

To solve these problems, RCI descriptors are introduced into the RCI specification.

RCI descriptors are XML documents that describe the content of RCI request and response documents. They describe all of the commands and parameters that RCI offers, as well as all of the configurable settings and state.

RCI descriptors exist for a particular device SKU. This allows descriptors to be exact for a given RCI target. RCI descriptors are constant given a certain set of variables, so they can be cached on a more coarse scale than per-device. Ideally, only the EDP device type and version would determine a unique descriptor.

The intention of the RCI descriptor is that it should stand on its own. That is, the contents of the descriptor must be complete enough such that a program iterating over the descriptor can identify all valid commands and options and all allowed configurable settings and state, and all of the options available for the allowed configurable settings and state. The goal is that this program should be able to display a generic GUI to a user using the information in the descriptor. This generic GUI should be complete in RCI function and be able to configure all supported settings and state in a reasonably user-friendly way.

This generic GUI will be referred to throughout this document as the prototypical RCI descriptor consumer.

The generic GUI is not part of this specification. It is assumed that a production quality GUI built from descriptors will have additional customized features not found in the descriptors. Furthermore, there may be exceptions to the above because of practical considerations. For instance, some settings may be too complex to allow the descriptors to be fully self-describing. In this case, extra knowledge will be needed by the consumer of the descriptor. These exceptions will be made obvious though, by for instance, use of “custom” types.

Note The goal of RCI descriptors is not to replicate the device web interface (if it has one). The look and feel and content of a generic GUI will be different than the web UI.

In addition to the goals above, other goals of descriptors include:

Keep the design as simple as possible. Do not attempt to capture the outlier cases.
Make exceptions to rules obvious, for example, by use of “custom” types.
Structure descriptors so that generating descriptors is relatively straightforward. Firmware engineers will be the primary writers of the descriptors. Descriptors need to be friendly to the embedded environment.

RCI descriptors are retrievable directly from the target device. This is highly desirable, since no a priori knowledge of a target device is needed. Also, often the allowed parameters for a command may be determined in firmware, so the same logic can be used to generate the descriptor, thus eliminating the effort in creating a separate descriptor and the possibility of getting the descriptor and actual implementation out of sync. However, due to practical considerations on the device, such as RAM and/or flash availability, it is not required that descriptors are dynamically accessible from the target. If a device does not allow for dynamic retrieval of descriptors, the descriptor for that target must be separately accessible and provisioned into Remote Manager by EDP device type and firmware level.

Note RCI descriptors are required for Remote Manager support.