Signal control events

Optima manages signal control events, providing capabilities based on DATEX II extensions:

The <situationPublicationExtension> node hosts the XML structure that implements the signal control extensions. 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>
            <country>it</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="..." id="..." version="...">
                     ..........
                     ..........
                </signalOperatorAction>
            </signalActionPublication>
        </situationPublicationExtension>
    </payloadPublication>
</d2LogicalModel>

The <signalOperatorAction> events contain information about the signal parameters that were changed with respect the default settings. Those events are typically used in scenario evaluation or integration of real-time adaptive signal controllers.

The <signalOperatorAction> node is characterized by three attributes:

Attributes Description

type

Identifier of the action type.

You can dispose of eight distinct values:

  • DynamicStageProgram
  • DynamicInterStageProgram
  • DynamicSignalGroupProgram
  • SignalControllerUpdate
  • SignalGroupAction
  • SignalStageAction
  • StreetSignalAction
  • TurnSignalAction

id

Identifier of the signal operator action.

version

Identifier of the signal operator action version.

Every <signalOperatorAction> action type is identified by several attributes:

Allows to insert a new stage-based program.

The available parameters are:

Parameter Description

controllerID

Identifier of the controller, determined during the modeling assessment.

It is mandatory.

Data type: String

Unit of measure: Not applicable.

Default value: Not applicable.

newProgramID

Identifier of the new signal program.

It is optional.

If newProgramID is not specified, I'm going to create a new dynamic program in "real-time", therefore not "model based".

In this case, it is necessary to provide, into the payload, the complete new program, otherwise TRE ignores the event.

If newProgramID is specified, it must be a negative number -N, where N is the identifier associated to a program already existing that you want update (in some specific elements).

Data type: Integer.

Unit of measure: Not applicable.

Default value: Not applicable.

name

Name of the new signal program.

Data type: String

Unit of measure: Not applicable.

Default value: Not applicable.

cycleTime

Allows to set the signal program cycle time.

It must be a value => 0.

Data type: Integer.

Unit of measure: [s].

Default value: Not applicable.

offset

Allows to set the new signal program offset.

The value must be contained in the interval [0, cycleTime].

Data type: Integer.

Unit of measure: [s].

Default value: Not applicable.

signalTiming

Allows to set a dynamic signal program timing.

Generally you find a list of elements signalTiming, alike in the example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>...</publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="DynamicStageProgram" id="CTRL_556_2" version="1">
                    <situationVersionTime>2018-12-05T00:00:00.000+01:00</situationVersionTime>
                    <validity>...</validity>
                    ...other elements...
                    ...
                    <signalTiming  xsi:type="GreenShareTiming">
                        <signalizationObjectID>1</signalizationObjectID>
                        <greenShare>0.03451</greenShare>
                    </signalTiming>
                    <signalTiming  xsi:type="GreenShareTiming">
                        <signalizationObjectID>2</signalizationObjectID>
                        <greenShare>0.0432421</greenShare>
                    </signalTiming>
                ...other elements...
</d2LogicalModel>

You must specify:

  • signalizationObjectID: Integer identifier of an existing stage of the controller (mandatory).

    Important:  Controllers have signal groups, possible stages and interstages, that can not be created dynamically (inserted) but their timings can be edited within the context of a signal program.

    Important:  ONE and ONLY ONE of the two following items is mandatory.

  • greenShare: Average share of green time during cycle time. Real value in [0, 1], measured in seconds.
  • greenStartTime (and associated greenEndTime): Green light start time (and green light end time) within cycle time. Real value, measured in seconds.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex2import/optima/?publish=TRUE

Request body (payload)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>
            <country>it</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="DynamicStageProgram" id="PIPPO_CTRL_556_2" version="1">
                    <situationVersionTime>2018-12-05T00:00:00.000+01:00</situationVersionTime>
                    <validity>
                        <validityStatus>definedByValidityTimeSpec</validityStatus>
                        <validityTimeSpecification>
                            <overallStartTime>2018-12-05T00:00:00.000+01:00</overallStartTime>
                        </validityTimeSpecification>
                    </validity>
                    <generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision.</generalPublicComment>
                    <controllerID>27</controllerID>
                    <cycleTime>91</cycleTime>
                    <offset>20</offset>  <!-- optional -->
                    <name>Hello GROUP-Share</name> <!-- optional -->
                    <signalTiming  xsi:type="GreenShareTiming">
                        <signalizationObjectID>1</signalizationObjectID>
                        <greenShare>0.03451</greenShare>
                    </signalTiming>
                    <signalTiming  xsi:type="GreenShareTiming">
                        <signalizationObjectID>2</signalizationObjectID>
                        <greenShare>0.0432421</greenShare>
                    </signalTiming>
                    <signalTiming  xsi:type="GreenShareTiming">
                        <signalizationObjectID>3</signalizationObjectID>
                        <greenShare>0.821</greenShare>
                    </signalTiming>
                </signalOperatorAction>
            </signalActionPublication>
        </situationPublicationExtension>
    </payloadPublication>
</d2LogicalModel>

Additional Notes

Here we have a specific combination composed by:

  • <signalOperatorAction> - "DynamicStageProgram"
  • <signalTiming> - "GreenShareTiming"

Allows to insert a new interstage program.

The available parameters are:

Parameter Description

controllerID

Identifier of the controller, determined during the modeling assessment.

It is mandatory.

Data type: String

Unit of measure: Not applicable.

Default value: Not applicable.

newProgramID

Identifier of the new signal program.

It is optional.

If newProgramID is not specified, I'm going to create a new dynamic program in "real-time", therefore not "model based".

In this case, it is necessary to provide, into the payload, the complete new program, otherwise TRE ignores the event.

If newProgramID is specified, it must be a negative number -N, where N is the identifier associated to a program already existing that you want update (in some specific elements).

Data type: Integer.

Unit of measure: Not applicable.

Default value: Not applicable.

name

Name of the new signal program.

Data type: String

Unit of measure: Not applicable.

Default value: Not applicable.

cycleTime

Allows to set the signal program cycle time.

It must be a value => 0.

Data type: Integer.

Unit of measure: [s].

Default value: Not applicable.

offset

Allows to set the new signal program offset.

The value must be contained in the interval [0, cycleTime].

Data type: Integer.

Unit of measure: [s].

Default value: Not applicable.

signalTiming

Allows to set a dynamic signal program timing.

Generally you specify a list of elements signalTiming (alike → Signal control events).

You must specify:

  • signalizationObjectID: Integer identifier of an existing inter stage of the controller (mandatory).

    Important:  Controllers have signal groups, possible stages and interstages, that can not be created dynamically (inserted) but their timings can be edited within the context of a signal program.

  • greenStartTime (and associated greenEndTime): Green light start time (and green light end time) within cycle time. Real value, measured in seconds.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex2import/optima/?publish=TRUE

Request body (payload)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>
            <country>it</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="DynamicInterStageProgram" id="PIPPO_CTRL_556_2" version="1">
                    <situationVersionTime>2018-12-05T00:00:00.000+01:00</situationVersionTime>
                    <validity>
                        <validityStatus>definedByValidityTimeSpec</validityStatus>
                        <validityTimeSpecification>
                            <overallStartTime>2018-12-05T00:00:00.000+01:00</overallStartTime>
                        </validityTimeSpecification>
                    </validity>
                    <generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision.</generalPublicComment>
                    <controllerID>27</controllerID>
                    <newProgramID>-2</newProgramID> <!-- newProgramID is optional and is better to avoid specifying it. If specified, it must be negative -->
                    <cycleTime>90</cycleTime>
                    <offset>5</offset>
                    <name>Hello STAGE-Interval</name>
                    <greenIntervalTiming>
                        <signalizationObjectID>7</signalizationObjectID>
                        <greenStartTime>90</greenStartTime>
                        <greenEndTime>5</greenEndTime> <!-- optinal, it is written to db but should be ignored in interstage --> 
                    </greenIntervalTiming>
                    <greenIntervalTiming>
                        <signalizationObjectID>8</signalizationObjectID>
                        <greenStartTime>9</greenStartTime>
                    </greenIntervalTiming>
                    <greenIntervalTiming>
                        <signalizationObjectID>11</signalizationObjectID>
                        <greenStartTime>19</greenStartTime>
                    </greenIntervalTiming>
                </signalOperatorAction>
            </signalActionPublication>
        </situationPublicationExtension>
    </payloadPublication>
</d2LogicalModel>

Allows to insert a new dynamic signal group program.

The available parameters are:

Parameter Description

controllerID

Identifier of the controller, determined during the modeling assessment.

It is mandatory.

Data type: String

Unit of measure: Not applicable.

Default value: Not applicable.

newProgramID

Identifier of the new signal program.

It is optional.

If newProgramID is not specified, I'm going to create a new dynamic program in "real-time", therefore not "model based".

In this case, it is necessary to provide, into the payload, the complete new program, otherwise TRE ignores the event.

If newProgramID is specified, it must be a negative number -N, where N is the identifier associated to a program already existing that you want update (in some specific elements).

Data type: Integer.

Unit of measure: Not applicable.

Default value: Not applicable.

name

Name of the new signal program.

Data type: String

Unit of measure: Not applicable.

Default value: Not applicable.

cycleTime

Allows to set the signal program cycle time.

It must be a value => 0.

Data type: Integer.

Unit of measure: [s].

Default value: Not applicable.

offset

Allows to set the new signal program offset.

The value must be contained in the interval [0, cycleTime].

Data type: Integer.

Unit of measure: [s].

Default value: Not applicable.

signalTiming

Allows to set a dynamic signal program timing.

Generally you find a list of elements signalTiming (alike → Signal control events).

You must specify:

  • signalizationObjectID: Integer identifier of an existing stage of the controller (mandatory).

    Important:  Controllers have signal groups, possible stages and interstages, that can not be created dynamically (inserted) but their timings can be edited within the context of a signal program.

    Important:  ONE and ONLY ONE of the two following items is mandatory.

  • greenShare: Average share of green time during cycle time. Real value in [0, 1], measured in seconds.
  • greenStartTime (and associated greenEndTime): Green light start time (and green light end time) within cycle time. Real value, measured in seconds.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex2import/optima/?publish=TRUE

Request body (payload)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>
            <country>it</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="DynamicSignalGroupProgram" id="PIPPO_CTRL_556_2" version="1">
                    <situationVersionTime>2018-12-05T00:00:00.000+01:00</situationVersionTime>
                    <validity>
                        <validityStatus>definedByValidityTimeSpec</validityStatus>
                        <validityTimeSpecification>
                            <overallStartTime>2018-12-05T00:00:00.000+01:00</overallStartTime>
                        </validityTimeSpecification>
                    </validity>
                    <generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision.</generalPublicComment>
                    <controllerID>27</controllerID>
                    <cycleTime>91</cycleTime> 
                    <!-- <offset>6</offset> -->  <!-- optional -->
                    <name>Hello GROUP-Share</name>
                    <signalTiming  xsi:type="GreenShareTiming">
                        <signalizationObjectID>1</signalizationObjectID>
                        <greenShare>0.2321</greenShare>
                    </signalTiming>
                    <signalTiming  xsi:type="GreenShareTiming">
                        <signalizationObjectID>2</signalizationObjectID>
                        <greenShare>0.021</greenShare>
                    </signalTiming>
                </signalOperatorAction>
            </signalActionPublication>
        </situationPublicationExtension>
    </payloadPublication>
</d2LogicalModel>

Additional Notes

Here we have a specific combination composed by:

  • <signalOperatorAction> - "DynamicSignalGroupProgram"
  • <signalTiming> - "GreenShareTiming"

Allows to specify:

  • The signal controller program.
  • The current cycle time.
  • The offset.

The available parameters are:

Parameter Description

controllerID

Identifier of the controller, determined during the modeling assessment.

It is mandatory.

Data type: String

Unit of measure: Not applicable.

Default value: Not applicable.

programID

Identifier of the signal program.

Can be an existing signal program or 0, that means Flashing amber program.

Data type: Integer

Unit of measure: Not applicable.

Default value: Not applicable.

cycleTime

Allows to set the signal program cycle time.

It must be a value => 0.

Data type: Integer.

Unit of measure: [s].

Default value: Not applicable.

offset

Allows to set the signal program offset.

The value must be contained in the interval [0, cycleTime].

Data type: Integer.

Unit of measure: [s].

Default value: Not applicable.

Specific conditions and constraints

Condition Constraint

Signal program has a green type green interval

cycleTime:

  • Must be NOT PRESENT

  • Must be cycleTime=NULL

offset must be a value contained in the interval [0, sprg.cycl] is the value set by model.

Signal program has a green type green share

Must be cycleTime>=0

offset:

  • Must be NOT PRESENT

  • Must be offset=NULL

ProgramID=0 (Flashing amber)

cycleTime and offset

  • Both parameters must be NOT PRESENT

  • Must be cycleTime=NULL and offset=NULL

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex2import/optima/?publish=TRUE

Request body (payload)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>
            <country>it</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="SignalControllerUpdate" id="ACTION_CTRL_556_2" version="1">
                     <situationVersionTime>2018-12-05T00:00:00.000+01:00</situationVersionTime>
                     <validity>
                         <validityStatus>definedByValidityTimeSpec</validityStatus>
                         <validityTimeSpecification>
                             <overallStartTime>2018-12-05T00:00:00.000+01:00</overallStartTime>
                         </validityTimeSpecification>
                     </validity>
                     <generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision.</generalPublicComment>
                     <controllerID>3</controllerID>
		      <cycleTime>4</cycleTime>					
                     <programID>2</programID>
                </signalOperatorAction>
            </signalActionPublication>
        </situationPublicationExtension>
    </payloadPublication>
</d2LogicalModel>

Additional Notes

In the <signalOperatorAction> node is mainly specified:

  • The action type to be performed through the parameter type "SignalControllerUpdate".
  • The action involved through the parameter id="ACTION_CTRL_556_2".
  • The temporal validity of the action (<validity> node).
  • The controller involved (<controllerID> node) and all the necessary parameters (in this example <programID>, <cycleTime>, and <offset>).

You can switch-off a signal controller, during the event validity, using a payload of type "SignalControllerUpdate" with <programID>=0.

Important:  The value 0 is a protected keyword: no signal program is allowed to have ID = 0.

The value <programID> 0 skips the consistency check and accepts the command as Switch off controller.

In this example, the <controllerID>=3 is switched off.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>
            <country>it</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="SignalControllerUpdate" id="ACTION_CTRL_556_2" version="1">
                     <situationVersionTime>2018-12-05T00:00:00.000+01:00</situationVersionTime>
                     <validity>
                         <validityStatus>definedByValidityTimeSpec</validityStatus>
                         <validityTimeSpecification>
                             <overallStartTime>2018-12-05T00:00:00.000+01:00</overallStartTime>
                         </validityTimeSpecification>
                     </validity>
                     <generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision.</generalPublicComment>
                     <controllerID>3</controllerID>
                     <programID>0</programID>
                </signalOperatorAction>
            </signalActionPublication>
        </situationPublicationExtension>
    </payloadPublication>
</d2LogicalModel>

Allows to specify the green share for an existing signal group.

The available parameters are:

Parameter Description

controllerID

Identifier of the controller, determined during the modeling assessment.

It is mandatory.

Data type: String

Unit of measure: Not applicable.

Default value: Not applicable.

signalGroupID

Identifier of the signal group program.

It is mandatory.

Data type: String

Unit of measure: Not applicable.

Default value: Not applicable.

GreenShare

Average share of green time during cycle time. Real value in [0, 1], measured in seconds.

It is mandatory.

Data type: Real.

Unit of measure: [s].

Default value: Not applicable.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex2import/optima/?publish=TRUE

Request body (payload)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>
            <country>it</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="SignalGroupAction" id="SIGGroup_556_2" version="2">
                     <situationVersionTime>2018-12-05T00:00:00.000+01:00</situationVersionTime>
                     <validity>
                         <validityStatus>definedByValidityTimeSpec</validityStatus>
                         <validityTimeSpecification>
                             <overallStartTime>2018-12-05T00:00:00.000+01:00</overallStartTime>
                         </validityTimeSpecification>
                     </validity>
                     <generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision.</generalPublicComment>
                     <controllerID>3</controllerID>
                     <signalGroupID>2</signalGroupID>
                     <greenShare>0.33</greenShare>
                </signalOperatorAction>
                <signalOperatorAction xsi:type="SignalGroupAction" id="SIGGroup_556_3" version="2">
                     <situationVersionTime>2018-12-05T00:00:00.000+01:00</situationVersionTime>
                     <validity>
                         <validityStatus>definedByValidityTimeSpec</validityStatus>
                         <validityTimeSpecification>
                             <overallStartTime>2018-12-05T00:00:00.000+01:00</overallStartTime>
                         </validityTimeSpecification>
                     </validity>
                     <generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision.</generalPublicComment>
                     <controllerID>3</controllerID>
                     <signalGroupID>3</signalGroupID>
                     <greenShare>0.33</greenShare>
                </signalOperatorAction>
            </signalActionPublication>
        </situationPublicationExtension>
    </payloadPublication>
</d2LogicalModel>

Additional Notes

In the <signalOperatorAction> node is mainly specified:

  • The action type to be performed through the parameter type="SignalGroupAction".
  • The action involved through the parameter id="SIGGroup_556_2".
  • The temporal validity of the action (<validity> node).
  • The controller involved (<controllerID> node) and all the necessary parameters (in this example <signalGroupID>, and <greenShare>).

Allows to specify the green share for an existing signal stage.

The available parameters are:

Parameter Description

controllerID

Identifier of the controller, determined during the modeling assessment.

It is mandatory.

Data type: String

Unit of measure: Not applicable.

Default value: Not applicable.

signalStageID

Identifier of the signal stage program.

It is mandatory.

Data type: String

Unit of measure: Not applicable.

Default value: Not applicable.

GreenShare

Average share of green time during cycle time. Real value in [0, 1], measured in seconds.

It is mandatory.

Data type: Real.

Unit of measure: [s].

Default value: Not applicable.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex2import/optima/?publish=TRUE

Request body (payload)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>
            <country>it</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="SignalStageAction" id="STAGE_556_2" version="2">
                     <situationVersionTime>2018-12-05T00:00:00.000+01:00</situationVersionTime>
                     <validity>
                         <validityStatus>definedByValidityTimeSpec</validityStatus>
                         <validityTimeSpecification>
                             <overallStartTime>2018-12-05T00:00:00.000+01:00</overallStartTime>
                         </validityTimeSpecification>
                     </validity>
                     <generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision.</generalPublicComment>
                     <controllerID>3</controllerID>
                     <signalStageID>2</signalStageID>
                     <greenShare>0.33</greenShare>
                </signalOperatorAction>
            <signalActionPublication>
        </situationPublicationExtension>
    </payloadPublication>
</d2LogicalModel>

Allows to specify the average green share and the signal cycle time for an existing street.

Parameter Description

streetLocation

Identifier of the controller, determined during the modeling assessment.

It is mandatory.

You must specify:

  • streetID: Integer identifier of an existing street (mandatory).

  • tailStreetNodeID: Integer identifier of the street tail node.

GreenShare

Average share of green time during cycle time. Real value in [0, 1], measured in seconds.

It is mandatory.

Data type: Real.

Unit of measure: [s].

Default value: Not applicable.

cycleTime

Allows to set the signal program cycle time.

It must be a value => 0.

Data type: Integer.

Unit of measure: [s].

Default value: Not applicable.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex2import/optima/?publish=TRUE

Request body (payload)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>
            <country>it</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="StreetSignalAction" id="ACTION_556_2" version="7">
                     <situationVersionTime>2018-12-05T00:00:00.000+01:00</situationVersionTime>
                     <validity>
                         <validityStatus>definedByValidityTimeSpec</validityStatus>
                         <validityTimeSpecification>
                             <overallStartTime>2018-12-08T14:00:00.000+01:00</overallStartTime>
                             <overallStartTime>2018-12-08T20:00:00.000+01:00</overallStartTime>
                             <validPeriod>
                                 <startOfPeriod>2018-12-06T00:00:00.000+01:00</startOfPeriod>
                                 <recurringTimePeriodOfDay xsi:type="TimePeriodByHour">
                                     <startTimeOfPeriod>03:22:00.000+01:00</startTimeOfPeriod
                                     <endTimeOfPeriod>16:24:00.000+01:00</endTimeOfPeriod>
                                 </recurringTimePeriodOfDay>
                                 <recurringDayWeekMonthPeriod>
                                     <applicableDay>friday</applicableDay>
                                 </recurringDayWeekMonthPeriod>
                             </validPeriod>
                         </validityTimeSpecification>
                     </validity>
                     <generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision.</generalPublicComment>
                     <streetLocation>
                         <streetID>565533001</streetID
                         <tailStreetNodeID>633479300</tailStreetNodeID>
                     </streetLocation>
                     <greenShare>0.0</greenShare>
                </signalOperatorAction>
            </signalActionPublication>
        </situationPublicationExtension>
    </payloadPublication>
</d2LogicalModel>

Allows to specify the average green share for an existing turn.

Parameter Description

turnLocation

Identifier of the location, composed by two streetLocation elements (see → StreetSignalAction).

It is mandatory.

You must specify:

  • fromStreetLink: streetLocation element.
  • toStreetLink: streetLocation element.

GreenShare

Average share of green time during cycle time. Real value in [0, 1], measured in seconds.

It is mandatory.

Data type: Real.

Unit of measure: [s].

Default value: Not applicable.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex2import/optima/?publish=TRUE

Request body (payload)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>
            <country>it</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="TurnSignalAction" id="ACTION_STURN_556_2" version="1">
                     <situationVersionTime>2018-12-05T00:00:00.000+01:00</situationVersionTime>
                     <validity>
                         <validityStatus>definedByValidityTimeSpec</validityStatus>
                         <validityTimeSpecification>
                             <overallStartTime>2018-12-05T00:00:00.000+01:00</overallStartTime>
                         </validityTimeSpecification>
                     </validity>
                     <generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision. Allow to specify the green share for an existing signal group.</generalPublicComment>
                     <turnLocation>
                         <fromStreetLink>
                             <streetID>565533001</streetID>
                             <tailStreetNodeID>633479300</tailStreetNodeID>
                         </fromStreetLink>
                         <toStreetLink>
                             <streetID>565533002</streetID>
                             <tailStreetNodeID>633479250</tailStreetNodeID>
                         </toStreetLink>
                     </turnLocation>
                     <greenShare>0.0</greenShare>
                 </signalOperatorAction>
            </signalActionPublication>
        </situationPublicationExtension>
    </payloadPublication>
</d2LogicalModel>

You can send distinct <signalOperatorAction> blocks at one time, distinguishing them by .id.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:ns2="http://datex2.eu/schema/2/2_0/com/sistemaits/ext">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication">
        <publicationCreator>
            <country>it</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situationPublicationExtension>
            <signalActionPublication>
                <signalOperatorAction xsi:type="DynamicStageProgram" id="controller_27_prg_rush_hour" version="1">
                </signalOperatorAction>
                <signalOperatorAction xsi:type="DynamicStageProgram" id="controller_25_prg_sunday" version="1">
                </signalOperatorAction>
            </signalActionPublication>
        </situationPublicationExtension>
    </payloadPublication>
</d2LogicalModel>

The response contains one line for each controller created:

actionid="controller_27_prg_rush_hour", version="1", "CONTROLLER_ID":27, sprgRltmIdno:"-1
actionid="controller_27_prg_sunday", version="1", "CONTROLLER_ID":27, sprgRltmIdno:"-1

Important:  Please do not rely on any order of the output lines.

Through the pair (id, version) you can distinguish the different operations run into the block <signalActionPublication>.

You can also manage six combinations of different values associated to the type attribute of two XML nodes:

  GreenIntervalTiming GreenShareTiming

DynamicStageProgram

 X X

DynamicInterstageProgram

 X Combination not applicable.

DynamicSignalGroupProgram

X X

Dynamic programs can be represented by describing the green red alternation (GreenIntervalTiming) or by specifying the capacity reduction applied to each maneuver (GreenShareTiming).

The combination of DynamicInterstageProgram with a GreenShareTiming does not make sense.

TRE can always calculate the green share corresponding to each maneuver starting from a DynamicInterstageProgram program with GreenIntervalTiming (→ Supply parameters > SignalPulse).

Important:  For Optima Micro (see → Optima Micro), the only valid combinations are DynamicInterstageProgram x GreenIntervalTiming or SignalControllerUpdate. The signal data (signal groups, stages, interstages) is consistent within the Optima data model and the micro subnetwork in PTV Vissim.

The response has a general structure:

<Main Message>
OK: Wrote <K/N> records
<!-- if K=N --> with following info:
<!-- if K<N --> with following errors/warnings:
<prefix> : <Human readable message>. <List of interesting parameters>

Where:

  • <Main Message>: The message that define the "meaning" and the "context" of the subsequent elements of the response message.
  • <prefix>: is built with the XML attributes id and version, associated to the element signalOperatorAction.
  • <Human readable message>: A message helping too understand the response.
  • <List of interesting parameters>: The value delivered in the XMLpayload like controllerID=27; val2=33; ...etc.
Successfully generated new signal controller program entry, with response of the idno.
OK: wrote 1/1 records
with following infos:
actionid="PIPPO_CTRL_556_9", version=1 : New Signal Controller Programm inserted. sprgRltmIdno=-7

Specifying a positive number as newProgramID will lead to an error.
OK: wrote 0/1 records
with following errors:
actionid="PIPPO_CTRL_556_9", version=1 : New Signal Program Id must be smaller than zero. : newProgramID=7
with following warnings:
No matching location found in DB for action with id PIPPO_CTRL_556_9 and version 1, it will be ignored

The event id is already used in db and no insert can be done
OK: wrote 0/1 records
with following errors:
actionid="PIPPO_CTRL_556_10", version=1 No update of event possible for New Signal Controller Program, please specify different event id. Skipping this action.

You should submit a payload without specify a <newProgramID>. Specifying it is possible, but it's better to let Optima generate it, to guarantee no conflicts with previously generated program IDs.

In this case, a new one is created.

For example, you can submit 3 new controllers, but without specify the <newProgramID> for one of them (see actionid="controller_27_prg_b").

In this case the response has a structure like this:

<Main Message>
OK: wrote 2/3 records
with following infos:
actionid="controller_27_prg_a", version=1, "new_signal_program_id"="-2", "CONTROLLER_ID"="27" 
actionid="controller_27_prg_c", version=1, "new_signal_program_id"="-1", "CONTROLLER_ID"="27" 
with following errors:
actionid="controller_27_prg_b", version=1, "CONTROLLER_ID"="27", "new_signal_program_id"="-3"