Dispenser Independent API (DIAPI)

For DIAPI configurations, you require three participants:

• Broadsign Control Player: Responsible for playing content based on the events communicated. See Broadsign Control Player.
• 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 Broadsign Control 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 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, for example, 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: Broadsign Control 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, Broadsign Control 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 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:

  Copy

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

• Subscribe response:

  Copy

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

• DISPENSER_STATE event:

  Copy

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

• GRADE_SELECTED event:

  Copy

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

• DISPENSER_DATA event:

  Copy

  <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:

  Copy

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

• ERROR_DATA event:

  Copy

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

• HEARTBEAT EVENT:

  Copy

  <Event type = "HEARTBEAT"/>

To access the DIAPI properties:

1. Open your player's configuration profile properties.

2. Go to: Add-ons > Integrations.

   

Configure the DIAPI properties:

• 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.