New COM Outline Draft 0.6 October 2010 Content 1. Overview ................................................................................................... 4 2. Concepts................................................................................................... 5 2.1. 2.1.1. Property Service capabilities ...................................................... 5 2.1.2. Property COM Schema extensions ............................................ 5 2.2. Consumer ................................................................................... 6 2.2.2. Optional relay provider ............................................................... 6 2.2.3. Final provider .............................................................................. 7 2.2.4. Activity Service capabilities ........................................................ 7 2.2.5. Activity COM Schema extensions............................................... 7 Event ................................................................................................. 7 2.3.1. Event Service capabilities ........................................................... 8 2.3.2. Event COM Schema extensions ................................................. 8 COM service specifications..................................................................... 10 3.1. Property ........................................................................................... 10 3.1.1. General..................................................................................... 10 3.1.2. Usage ....................................................................................... 10 3.1.3. Common model usage ............................................................. 10 3.1.4. OPERATION: setProperty ........................................................ 11 3.2. Activity ............................................................................................. 12 3.2.1. General..................................................................................... 12 3.2.2. Usage ....................................................................................... 12 3.2.3. Common model usage ............................................................. 12 3.3. Event ............................................................................................... 13 3.3.1. General..................................................................................... 13 3.3.2. Usage ....................................................................................... 13 3.3.3. Common model usage ............................................................. 13 3.4. 4. Activity ............................................................................................... 6 2.2.1. 2.3. 3. Property ............................................................................................. 5 Retrieval .......................................................................................... 14 COM data types ...................................................................................... 15 4.1. New COM Structures ....................................................................... 15 4.2. Event structures............................................................................... 16 2 4.2.1. EventOccurrence ...................................................................... 16 4.2.2. EventStatus .............................................................................. 16 4.3. Property structures .......................................................................... 16 4.3.1. 4.4. 5. PropertyStatus .......................................................................... 17 Activity structures ............................................................................ 17 4.4.1. ActivityOccurrence.................................................................... 17 4.4.2. OperationOccurrence ............................................................... 18 4.4.3. ActivityStatus ............................................................................ 18 4.4.4. OperationStatus ....................................................................... 18 4.4.5. ActivityNotificationType ............................................................ 19 MO COM service example ...................................................................... 20 5.1. Deployment ..................................................................................... 20 5.2. PTU Service .................................................................................... 20 5.2.1. PTU .......................................................................................... 20 5.2.2. Data structures ......................................................................... 21 5.2.3. Service XML ............................................................................. 21 3 1. Overview The new COM extends the previous COM. As such it fulfills the following objectives: It defines an entity model that MO services extend and an associated set of operations for the management and observation of that model. By defining this standard service entity model it allows not only the specification of standard operations but also the definition of a standard historical archive and the associated services that support the archive. The new COM adds some new features and constraints: It shall be used by every MO service. This doesn’t mean that every MO service shall inherit from the COM operations. It means that the COM design rules shall be followed by every MO services (with COM inheritance or not). It defines specific entities (or type of entities) dedicated to MO services: o Property o Activity o Event Those entities are represented by the COM structures: Occurrence and Status. There is no use of Definition in these services to keep their implementation complexity down. Their creation shall be compliant with some design rules required by the new COM. It includes the Common::Retrieval service (it shall be moved from Common to COM) 4 2. Concepts The new COM concepts are extracted from the current Core area: Property (simplified version of Core::Parameter) Activity (simplified version of Core::Action) Event (simplified version of Core::Alert) These COM services are simplified versions of their Core counterparts, it is expected that the Core services are enhanced versions of these that add the dynamic Definition aspect not included in the COM versions. Other features may also be added by Core such as Check and Conversion services in Parameter. 2.1. Property A property contains a single MAL::Element. No information can be associated to the status of a property. Its status is only represented by a MAL::Element. The update interval of a property is implementation specific, it is not something that can be altered, except by service specific extensions. Updates that share the same updating interval are to be published at the same time gathered as a set of COM::PropertyStatus update objects and sent in a single MAL::UpdateList. The transport layer is responsible for building the packets and conveying them: the current service Core::Aggregation is therefore not useful any more from this “physical packet” point of view; however it may be retained for the dynamic definition aspect. 2.1.1. Property Service capabilities The COM::Property service extends COM::Status for the monitoring of properties and defines a capability for the setting of properties. The definition of the properties in the COM extended schema specifies whether the property is read only, if it is then the set operations shall reject its identifier. 2.1.2. Property COM Schema extensions The COM Schema contains extra elements in the service area that lists the set of properties, their type, and names: <com:properties> <com:property name="<name>" readOnly="false" comment=""> <smc:type name="Boolean" area="MAL"/> </com:property> <com:property name="<name>" readOnly="true" comment=""> <smc:type name="<type>" area="<area>" service="<service>"/> </com:property> </com:properties> </smc:service> 5 This ability to define properties can be created at the Service level and the Capability Set level. This allows properties to be capability set dependent. 2.2. Activity The declaration of Activity entities is given by the MO service definition: each operation tagged as a COM::Activity in the service XML represents an instance of Activity entity. An MO service must be a COM service in order to use this feature. Each marked operation defined by an MO service leads to a “Common Model Updates” behavior implemented by the Activity service provider. Any component type providing or consuming an MO service that has COM::Activity operation has also to provide the service COM::Activity. The Activity service provider is distributed in the MO service consumer and provider. Note: This behavior can be extended by defining other COM::Activity[Occurrence/Status] subtypes (e.g. the future Procedure service). 2.2.1. Consumer Before the interaction is initiated, an OperationOccurrence structure shall be archived and distributed using a CompleteOccurrenceUpdate structure. It shall use a MAL::UpdateType of Creation. After the interaction is ended, a CompleteOccurrenceUpdate structure shall be archived and distributed but setting the occurrence field to NULL. It shall use a MAL::UpdateType of Deletion. The intermediate stages don’t lead to any updates being published by the consumer. 2.2.2. Optional relay provider When an Operation is being passed via a relay provider, the following behaviour shall be seen. The following OperationStatus shall be archived and distributed using a CompleteStatusUpdate structure. 1. Upon reception of the interaction: o The update type shall be Modification. o The activity notification type shall be RECEPTION. o The OperationStatus fields messageHeader and messageBody are set to NULL. 6 2. Upon transmission of the interaction to the next provider (next destination): o The update type shall be Modification. o The activity notification type shall be FORWARD. o The OperationStatus fields messageHeader and messageBody are set to NULL. This pattern may be repeated for each relay provider. 2.2.3. Final provider The following OperationStatus shall be archived and distributed using a CompleteStatusUpdate structure. 1. Before the interaction is handled: o If the IP is SEND then the update type shall be DELETION else the update type shall be Modification. o The activity notification type shall be ACCEPTANCE. o The OperationStatus fields messageHeader and messageBody are set to NULL. 2. For each stage of the IP: o If it is the final stage of the IP (i.e. completed or an error is being returned) the update type shall be Deletion else it shall be MODIFICATION. o The activity notification type shall be EXECUTION. o The OperationStatus fields messageHeader and messageBody are assigned with the operation returned message header and body. 2.2.4. Activity Service capabilities The COM::Activity service extends COM and includes the standard Occurrence and Status capability sets for the monitoring of Activity progress. 2.2.5. Activity COM Schema extensions Each COM::Activity operation is marked as such as follows: <smc:invokeIP xsi:type="com:COMInvokeOperationType" ...> 2.3. Event Event partially replaces the current Core::Alert service. 7 A service defines the set of Events that it may raise during its lifetime. An event is defined as a type that extends COM::EventOccurrence and is listed in a special COM service of the service specification. A component can raise an Event at any time by publishing the event occurrence. If an operation is defined in a Service that has error codes, these can be marked as Event error codes in the XML, in this case an associated Event shall be published concurrently. There is COM service associated with events that allows Events to be monitored, however event generation control is through MO service specific extensions (this is something that Core::Alert will probably provide). An event shall be raised as a COM::CompleteOccurrenceUpdate structure with the occurrence set to a specific COM::EventOccurrence and a MAL::UpdateType of Deletion. 2.3.1. Event Service capabilities The COM::Event service extends COM and includes the standard Occurrence and Status capability sets for the monitoring of Events. 2.3.2. Event COM Schema extensions Each Service specific event is defined as a normal data type but it must extend COM::EventOccurrence: <smc:composite name="LimitEvent" shortForm="MIAPL" comment=""> <smc:extends> <smc:type name="EventOccurrence" area="COM" service="Event"/> </smc:extends> <smc:field name="direction" canBeNull="false" comment=""> <smc:type name="PointingDirection" area="MIA" service="PTU"/> </smc:field> </smc:composite> The COM Schema contains extra elements in the service area that lists the set of Event that this service will raise on the COM::Event PubSub channel: <com:eventsRaised> <com:event name="<event identifier>"> <smc:type name="LimitEvent" area="MIA" service="PTU"/> </com:event> </com:eventsRaised> 8 The COM Schema also allows operations that have already been identified as COM::Activities to augment any raised errors with the fact that the error will also be published on the COM::Event PubSub channel: </smc:messages> <smc:errors> <smc:errorRef xsi:type="com:COMErrorReferenceType" comment=""> <smc:type name="MAXIMUM" area="MIA" service="Cam"/> <smc:extraInformation comment=""> <smc:type name="LimitEvent" area="MIA" service="PTU"/> </smc:extraInformation> </smc:errorRef> </smc:errors> </smc:invokeIP> 9 3. COM service specifications 3.1. Property 3.1.1. General The Property service provides operations to monitor and set the Property values. Area Identifier Service Identifier COM Property Interaction Pattern Operation Name Area Number Service Number Service Version Operation Number Support in replay Capability Set All Common Model Status Operations SUBMIT setProperty 100 No 3.1.2. Usage The consumer can provision the property values and monitor the property status changes. 3.1.3. Common model usage The following Property service operations are COM operations: setProperty The Property service complies with the common archive model as follows: Definition Occurrence Status Structure Not used Not used PropertyStatus Update structures Not used Not used CompleteStatusUpdate The entity identifiers are assigned as follows: 10 Identifier field Definition Occurrence Status entityId Not used Not used <area>.<service>.<field> definitionId Not used Not used <service version> Not used Set to NULL occurrenceId statusId Linear integral sequence generated by the service provider The following variables are used in the table: area: name of the area where the service is defined service: name of the service that defines the property service version: version number of the service field: name of a field defining a property, from service specification 3.1.4. OPERATION: setProperty TBW 3.1.4.1. General TBW Operation Name setProperty Interaction Pattern SUBMIT IP Sequence Message Field Type IN Submit SetPropertyDetails 3.1.4.2. Structures TBW 3.1.4.3. Common Model Updates TBW 3.1.4.4. Errors Error UNKNOWN INVALID Error # Comments Unknown property Invalid value 11 3.2. Activity 3.2.1. General The Activity service provides operations to monitor operation occurrences and status. Area Identifier Service Identifier COM Activity Interaction Pattern Operation Name Area Number Service Number Service Version Operation Number Support in replay Capability Set All Common Model Occurrence Operations All Common Model Status Operations 3.2.2. Usage The consumer can monitor the operation occurrences creation, deletion and status changes. 3.2.3. Common model usage The Activity service complies with the common archive model as follows: Definition Occurrence Status Structure Not used ActivityOccurrence ActivityStatus Update structures Not used TBD TBD The entity identifiers are assigned as follows: Identifier field Definition Occurrence Status entityId Not used <area>.<service>.<operation> From occurrence definitionId Not used <service version> From occurrence <uri consumer>/ From occurrence occurrenceId <transaction id> statusId TBD The following variables are used in the table: 12 area: name of the area where the service is defined service: name of the service that provides the executed operation operation: name of the operation service version: version number of the service The statusId is still undecided. It needs to provide a simple progression that can be followed however there are potentially many providers involved in publishing updates for a single Activity and therefore there is a risk of overlap. 3.3. Event 3.3.1. General The Event service provides operations to monitor Event occurrences and status. Area Identifier Service Identifier COM Event Interaction Pattern Operation Name Area Number Service Number Service Version Operation Number Support in replay Capability Set All Common Model Occurrence Operations All Common Model Status Operations 3.3.2. Usage The consumer can monitor the Event occurrences creation, deletion and status changes if the Event type supports Status (basic model does not). 3.3.3. Common model usage The Event service complies with the common archive model as follows: Definition Occurrence Status Structure Not used EventOccurrence EventStatus Update structures Not used TBD TBD The entity identifiers are assigned as follows: 13 Identifier field Definition Occurrence Status entityId Not used <area>.<service>.<event> From occurrence definitionId Not used <service version> From occurrence TBD From occurrence occurrenceId statusId Linear integral sequence generated by the service provider The following variables are used in the table: area: name of the area where the service is defined service: name of the service that provides the event event: name of the event from service specification service version: version number of the service 3.4. Retrieval This service is the current Common::Retrieval service and is just moved into the COM area. 14 4. COM data types 4.1. New COM Structures Composite Composite DefinitionKey - Composite OccurrenceKey «ATTRIBUTE» entityId: Identifier «ATTRIBUTE» definitionId: Identifier StatusKey «ATTRIBUTE» entityId: Identifier «ATTRIBUTE» definitionId: Identifier «ATTRIBUTE» occurrenceId: Identifier - type:DefinitionKey - Composite Composite Composite Composite Composite Status «ATTRIBUTE» description: String Composite Composite Composite CompleteOccurrence key: DefinitionKey «ATTRIBUTE» timestamp: Time «ABSTRACT» definition: Definition - CompleteStatus key: OccurrenceKey «ATTRIBUTE» timestamp: Time «ABSTRACT» occurrence: Occurrence type:CompleteDefinition - key: StatusKey «ATTRIBUTE» timestamp: Time «ABSTRACT» status: Status type:CompleteOccurrence Composite Composite «LIST» CompleteOccurrenceList Update «LIST» CompleteStatusList Update DefinitionUpdate Update OccurrenceUpdate updateSource: UpdateSource - StatusUpdate updateSource: UpdateSource type:DefinitionUpdate type:OccurrenceUpdate Composite Composite «LIST» OccurrenceUpdateList CompleteDefinitionUpdate «LIST» StatusUpdateList CompleteOccurrenceUpdate «ABSTRACT» occurrence: Occurrence - type:StatusUpdate Composite «LIST» DefinitionUpdateList «ABSTRACT» definition: Definition type:CompleteStatus Composite «LIST» CompleteDefinitionList - Composite «LIST» StatusKeyList Occurrence CompleteDefinition - type:StatusKey «LIST» OccurrenceKeyList Definition - entityId: Identifier definitionId: Identifier occurrenceId: Identifier statusId: Identifier type:OccurrenceKey «LIST» DefinitionKeyList - «ATTRIBUTE» «ATTRIBUTE» «ATTRIBUTE» «ATTRIBUTE» CompleteStatusUpdate - «ABSTRACT» status: Status Composite UpdateSource - SimpleDefinition domain: DomainIdentifier «ATTRIBUTE» networkZone: Identifier «ATTRIBUTE» area: Short «ATTRIBUTE» service: Short sourceKey: OccurrenceKey SimpleOccurrence SimpleStatus 15 4.2. Event structures OccurrenceUpdate Ev entOccurrenceUpdate - «ABSTRACT» occurrence: EventOccurrence «ATTRIBUTE» errorNumber: Integer Occurrence Status EventOccurrence EventStatus 4.2.1. EventOccurrence Structure Name EventOccurrence Extends COM::Occurrence Abstract Field Type Comment 4.2.2. EventStatus Structure Name EventStatus Extends COM::Status Abstract Field Type Comment 4.3. Property structures Composite Status SetPropertyDetails -/ - key: StatusKey property: PropertyStatus PropertyStatus - «ABSTRACT» value: Element 16 4.3.1. PropertyStatus Structure Name PropertyStatus Extends COM::Status Short form xxx Field Type value Comment MAL::Element The value property of the 4.4. Activity structures Occurrence Status ActivityOccurrence - «ATTRIBUTE» nextDestination: URI «ATTRIBUTE» estimateTimestamp: Time «ATTRIBUTE» success: Boolean ActivityStatus - «ATTRIBUTE» nextDestination: URI «ATTRIBUTE» estimateTimestamp: Time «ATTRIBUTE» success: Boolean «enumeration» notificationType: ActivityNotificationType OperationOccurrence - originalMessageHeader: MessageHeader originalMessageBody: Element «enumeration» Activ ityNotificationType OperationStatus - returnMessageHeader: MessageHeader returnMessageBody: Element + + + + «enum» «enum» «enum» «enum» RECEPTION: ActivityNotificationType = 1 FORWARD: ActivityNotificationType = 2 ACCEPTANCE: ActivityNotificationType = 3 EXECUTION: ActivityNotificationType = 4 4.4.1. ActivityOccurrence Structure Name ActivityOccurrence Extends COM::Occurrence Abstract Field Type nextDestination MAL::URI estimateTimestamp MAL::Time success MAL::Boolean Comment 17 4.4.2. OperationOccurrence Structure Name OperationOccurrence Extends COM::ActivityOccurrence Short form xxx Field Type Comment messageHeader MAL::MessageHeader messageBody MAL::Element 4.4.3. ActivityStatus Structure Name ActivityStatus Extends COM::Status Abstract Field Type Comment nextDestination MAL::URI estimateTimestamp MAL::Time success MAL::Boolean notificationType COM::Activity::ActivityNotificationType 4.4.4. OperationStatus Structure Name OperationStatus Extends COM::Activity::ActivityStatus Short form xxx Field Type messageHeader MAL::MessageHeader messageBody MAL::Element Comment 18 4.4.5. ActivityNotificationType Enumeration Name ActivityNotificationType Short form xxx Enumeration Value Short form RECEPTION 1 FORWARD 2 ACCEPTANCE 3 EXECUTION 4 Comment 19 5. MO COM service example 5.1. Deployment Controller PTU Component PTU Protocol PTU Activity Event Protocol Property Event Property Protocol Video Display Video feed 5.2. PTU Service The PTU (Pan Tilt Unit) service provides a service for the monitor and control of a PTU. The PTU service extends the COM and defines COM::Properties and as a consequence an implementation is required to provide the COM:Property service. 5.2.1. PTU Area Identifier Service Identifier MIA PTU Interaction Pattern Operation Name Area Number Service Number Service Version 1 Operation Number Support in replay Capability Set All Common Model Occurrence Operations INVOKE pointAt No 100 SUBMIT track No 101 COM Model usage 20 Definition Occurrence Status Structure Not Used COM:: SimpleOccurrence Not Used Update structures Not Used COM:: CompleteOccurrenceUpdate Not Used COM Activities pointAt track COM Events LimitReached LostLock COM Properties pointingDirection trackMode 5.2.2. Data structures PointRequest -/ -/ PTUOccurrence: OccurrenceKey direction: PointingDirection PointingDirection -/ -/ -/ «ATTRIBUTE» x: Double «ATTRIBUTE» y: Double «ATTRIBUTE» z: Double EventOccurrence LimitEv ent -/ EventOccurrence LostLockEv ent direction: PointingDirection 5.2.3. Service XML <?xml version="1.0" encoding="UTF-8"?> <smc:specification xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 21 xmlns:smc="http://www.ccsds.org/schema/ServiceSchema" xmlns:com="http://www.ccsds.org/schema/COMSchema"> <smc:area name="MIA" number="100"> <smc:service xsi:type="com:COMServiceType" name="PTU" number="1" version="1"> <smc:capabilitySet number="100"> <smc:invokeIP number="100" xsi:type="com:COMInvokeOperationType" name="pointAt" supportInReplay="false" comment=""> <smc:messages> <smc:invoke> <smc:type name="PointRequest" area="MIA" service="PTU"/> </smc:invoke> <smc:acknowledgement> <smc:type name="OccurrenceKey" area="COM" service="COM"/> </smc:acknowledgement> <smc:response> <smc:type name="PointingDirection" area="MIA" service="PTU"/> </smc:response> </smc:messages> <smc:errors> <smc:errorRef any further"> xsi:type="com:COMErrorReferenceType" comment="Cannot move <smc:type name="MAXIMUM" area="MIA"/> <smc:extraInformation comment="The PTU has reached a maximum"> <smc:type name="LimitEvent" area="MIA" service="PTU"/> </smc:extraInformation> </smc:errorRef> <smc:errorRef comment="Requested direction is not supported"> <smc:type name="INVALID" area="COM" service="COM"/> </smc:errorRef> </smc:errors> </smc:invokeIP> </smc:capabilitySet> <smc:capabilitySet xsi:type="com:COMCapabilitySetType" number="101"> <smc:submitIP xsi:type="com:COMSubmitOperationType" name="track" number="101" supportInReplay="false" comment=""> <smc:messages> <smc:submit> <smc:type name="PointRequest" area="MIA" service="PTU"/> </smc:submit> </smc:messages> </smc:submitIP> <com:eventsRaised> <com:event name="lostLock"> 22 <smc:type name="LostLockEvent" area="MIA" service="PTU"/> </com:event> </com:eventsRaised> <com:properties> <com:property name="trackMode" canBeNull="false" readOnly="false" comment="Is the PTU in auto tracking mode"> <smc:type name="Boolean" area="MAL"/> </com:property> </com:properties> </smc:capabilitySet> <smc:dataTypes> <smc:composite name="LimitEvent" shortForm="MIAPL" comment=""> <smc:extends> <smc:type name="EventOccurrence" area="COM" service="Event"/> </smc:extends> <smc:field direction"> name="direction" canBeNull="false" comment="Last pointing <smc:type name="PointingDirection" area="MIA" service="PTU"/> </smc:field> </smc:composite> <smc:composite name="LostLockEvent" shortForm="MIAPO" comment=""> <smc:extends> <smc:type name="EventOccurrence" area="COM" service="Event"/> </smc:extends> </smc:composite> <smc:composite name="PointingDirection" shortForm="MIAPV" comment="Pointing direction unit vector"> <smc:field name="x" canBeNull="false" comment="X component"> <smc:type name="Double" area="MAL"/> </smc:field> <smc:field name="y" canBeNull="false" comment="Y component"> <smc:type name="Double" area="MAL"/> </smc:field> <smc:field name="z" canBeNull="false" comment="Z component"> <smc:type name="Double" area="MAL"/> </smc:field> </smc:composite> <smc:composite name="PointRequest" shortForm="MIAPR" comment=""> <smc:field name="PTUOccurrence" canBeNull="false" comment="Unit to point"> <smc:type name="OccurrenceKey" area="COM" service="COM"/> </smc:field> <smc:field name="direction" canBeNull="false" comment="Pointing direction"> <smc:type name="PointingDirection" area="MIA" service="PTU"/> </smc:field> </smc:composite> </smc:dataTypes> 23 <com:extendsOccurrence> <com:capabilitySet number="1"/> <com:updateType name="CompleteOccurrenceUpdate" area="COM" service="COM"/> <com:objectType name="SimpleOccurrence" area="COM" service="COM"/> </com:extendsOccurrence> <com:eventsRaised> <com:event name="limitReached"> <smc:type name="LimitEvent" area="MIA" service="PTU"/> </com:event> </com:eventsRaised> <com:properties> <com:property name="pointingDirection" canBeNull="false" comment="Unit vector for the pointing direction"> <smc:type name="PointingDirection" area="MIA" service="PTU"/> </com:property> </com:properties> </smc:service> <smc:service xsi:type="com:COMServiceType" name="Camera" number="2" version="1"/> <smc:service xsi:type="com:COMServiceType" name="Encoder" number="3" version="1"/> <smc:errors> <smc:error name="MAXIMUM" number="80000" comment="A maximum has been reached"/> </smc:errors> </smc:area> </smc:specification> 24