The introductory article explains the concept of REST and UDP sinks. REST sinks require applications to periodically send requests to the server to get the current data. Sometimes, however, this form of communication isn’t desirable, like with traffic light controllers which require current updates as fast as possible or aren’t able to send frequent data requests. UDP sinks offer an alternative thanks to their usage of the UDP protocol: Subscribe to a sink once and get a zone's status updates until the subscription expires. 

After assigning a UDP sink to an operator, any authorized client application can start communicating with the server via UDP packets, whose payloads are JSON objects. At this moment, UDP communication doesn't use any form of authentication. The UDP server listens on the port 55570 (default setting).

There are two types of UDP sinks: Zone state sink and category count sink.
        

Zone state sink

This sink is subscription-based and provides information about the object presence and sensor state of a corresponding zone.

A typical procedure for your application would be to subscribe to a FLOW server with a ZoneStateSubscribe message and then wait for ZoneStatePush messages. Immediately after subscription, the server sends Push messages for all active sinks - one Push message per sink per UDP datagram. Then until the subscription timeout expires, the server automatically sends Push messages for sinks whose state has changed. Another ZoneStateSubscribe message with the same destination IP address and port will reset the timer.

Apart from that, a device may request extended data from a zone state sink by sending the ZoneExtendedStateRequest. Afterward, a response from all zone state sinks specified in the request is generated - one response per sink per UDP datagram.
      

ZoneStateSubscribe

Direction: To server
Example payload:

{
  "ZoneStateSubscribe": {
    "DestinationIpAddress": "192.168.11.1",
    "DestinationPort": 4444,
    "SubscriptionTimeout_s": 10
  }
}

Description: The message contains an IP address and port of the device that should receive ZoneStatePush messages for the duration of the timeout.
      

ZoneStatePush

Direction: From server to the address specified by the ZoneStateSubscribe message
Example payload:

{
  "ZoneStatePush": {
        "Id": "z001",
        "Failure": false,
        "FailureState": "NoFailure",
        "Presence": true
  }
}

Description:

  • Id - the identifier of the corresponding sink
  • Failure - denotes whether there is a failure within a sensor watching the zone
  • Presence - denotes whether there is a traffic object within the zone

FailureState - a string describing the failure state, can have the following values:

  • NoFailure
  • SensorFailure - failure of the camera, sensor, or another internal component
  • CommunicationFailure
  • ConfigurationFailure - invalid configuration, e.g. the corresponding zone doesn’t exist
  • EnvironmentalInterference - e.g. camera blinded by the Sun, reflections on the road, fog, darkness, frost
  • SensorCalibration - the system is still initializing and cannot provide detection data yet

      

ZoneExtendedStateRequest

Direction: To server
Example payload:

{
  "ZoneExtendedStateRequest": {
    "Sinks": [ "z001", "z002" ]
  }
}

Description:

  • Sinks - an array of strings denoting which sinks’ extended data the sender wants to receive

      

ZoneExtendedState

Direction: From server to the request sender
Example payload:

{
  "ZoneExtendedState": {
    "Id": "z002",
    "VehicleCount": 24,
}

Description:

  • Id - the identifier of the corresponding sink
  • VehicleCount - number of vehicles in the zone
  • The ZoneExtendedState object may actually have more properties, but their values will always be invalid, so it's safe to ignore them.     

Category count sink

This sink provides data from a continuous counter of trajectories sorted into categories. The counter resets only when the underlying integer data type overflows. Data from this sink is obtained by requesting them. After sending one request, a response from all Category Count Sinks is generated - one response per sink per UDP datagram.  
    

CategoryCountRequest

Direction: To server
Payload:

{
  "CategoryCountRequest": {}
}

      

CategoryCount

Direction: From server to the request sender
Example payload:

{
  "CategoryCount": {
    "Id": "m1",
       
    "CategoryCounts": [
      {
        "Category": "car",
        "Count": 10
      },
      {
        "Category": "pedestrian",
        "Count": 21
      }
    ]
  }
}

Description:

  • Id - the identifier of the corresponding sink
  • Category - a string containing the name of the category, to which the Count relates. Can have one of the following values: car, light, heavy, bus, motorcycle, bicycle, pedestrian, unknown

      

What next?

Communication with FLOW’s servers may not always go as planned. See the error reference document to learn more about them.

We will be happy to answer any questions you may have. Contact us!


Did this answer your question?