Dispenser Independent API

Participants

For DIAPI configurations, three participants are involved:

• The Broadsign Player: Responsible for playing content based on the events communicated.
• Third party software: Middleware responsible for implementing the DIAPI interface — not provided by Broadsign.
• Dispenser: The fuel dispenser’s internal software and hardware

Communication Flow

All communication between the Broadsign Player and the middleware will be over standard TCP/IP over a configurable port. The communication between the middleware and the dispenser will have to be achieved via existing proprietary APIs.

There are a number of features specific to the Dispenser Independent API protocol:

• XML over TCP/IP: The DIAPI protocol consists of a series of UTF-8 encoded XML messages sent and received over a standard TCP/IP connection. Each XML message is followed by a null byte (“”). The default TCP port for a DIAPI connection is 10999 and can be configured to any port over which the middleware and Player will be listening and connecting. In a similar fashion, by default the host to connect to is localhost and can be configured to any other host.
• Authentication/Encryption: The DIAPI protocol does not implement any form of authentication or encryption.
• Event Types: The following event types are supported by the DIAPI:
  • DISPENSER_STATE: This event is sent every time the state of the dispenser changes, e.g., CAR_PRESENT, FUELING.
  • GRADE_SELECTED: This event is sent when a fuel grade is selected.
  • DISPENSER_DATA: This event is sent when the dispensing operation begins. It carries information about pricing, currencies and units of measure.
  • TRANSACTION_DATA: This event is sent at a high frequency as the dispensing occurs. It is primarily responsible for transmitting the volume of fuel dispensed.
  • ERROR_DATA: This event is sent when any error occurs within the dispenser or with the connection between the middleware and dispenser.
  • HEARTBEAT: This event is sent by the middleware at regular intervals to inform clients that it is still operational.
• Implementation Specifics:
  • monitor_diapi: The Broadsign player implements a new monitor called monitor_diapi. It is responsible for establishing a TCP connection, issuing SubscribeRequests and interpreting the received messages.
  • Self Healing: If the TCP connection is impossible to establish or is severed, the Broadsign Player will retry every 15 seconds until established.
  • Error handling and reporting: If the connection fails after 8 attempts (2 min), an incident will be reported to the Broadsign Server. Once reestablished, the incident will get automatically resolved. Likewise, if an ERROR_DATA is received by the Player, an incident will be reported and resolved when a DISPENSER_STATE event is received. Finally, if a HEARTBEAT event is not received after 95 seconds (3 missed heartbeats + 5 sec buffer), an incident will be opened, the current connection will be dropped and a re-connect will be initiated.

The following XML samples indicate how to use the DIAPI:

• Subscribe Request:

  <SubscribeRequest>
    <event type="DISPENSER_STATE"/>
    <event type="TRANSACTION_DATA"/>
    <event type="HEARTBEAT"/>
  </SubscribeRequest >

• Subscribe Response:

  <SubscribeResponse>
    <event type="DISPENSER_STATE"/>
    <event type="TRANSACTION_DATA"/>
    <event type="HEARTBEAT"/>
  </SubscribeResponse >

• DISPENSER_STATE event:

  <Event type = "DISPENSER_STATE">
    <state name="IDLE"/>
  </Event>

• GRADE_SELECTED event:

  <Event type = "GRADE_SELECTED">
    <grade id="1"/>
  </Event>

• DISPENSER_DATA event:

  <Event type = "DISPENSER_DATA">
    <dispenser_data
      pump_number="4"
      currency=" €"
      volume_unit="L" />
    <grades>
      <grade id="1" price="1,398" />
  	<grade id="1" price="1,398" />
      <grade id="3" price="1" />
    </grades> 
  </Event> 

• TRANSACTION_DATA event:

  <Event type = "ERROR_DATA">
    <error id="1">Connection with calculator lost</error>
  </Event>

• ERROR_DATA event:

  <Event type = "ERROR_DATA">
    <error id="1">Connection with calculator lost</error>
  </Event>

• HEARTBEAT event:

  <Event type = "HEARTBEAT"/>

You can remotely configure the following items:

• Enabling/disabling the DIAPI integration (disabled by default).
• The hostname and port to connect to (default localhost:10999).
• Conditions and triggers to set when a GRADE_SELECTED event is received.
• Conditions and triggers to set when a DISPENSER_STATE is received.
• Trigger: Will immediately change the loop (potentially truncating content).
• Play Next Trigger: Will wait for the current content to end before changing the loop.
• Interrupt: When this option is enabled, the loop will be interrupted. A set of frame criteria must be selected to indicate on which frame the interrupt should be applied.
• Alternating conditions: A list of conditions that will alternate each time that type is received.
• Reset loop when dispenser state changes: If enabled, this will reset the loop to the beginning each time the dispenser state changes. Useful if a specific play order is desired each time instead of resuming where it last left off.
• Edit: Edit the conditions and triggers for the selected grade or state.
• Remove: Clear the conditions and triggers for the selected grade or state. If remove is clicked a second time once all the conditions and triggers have been cleared, the user will be prompted “Are you sure to wish to remove [$string]?” where $string is the selected grade or state. If confirmed, it is removed from the list of grades and states.
• Define New: When clicked, allows the user to define a new, arbitrary grade or dispenser state.