ReelData System & Feed Control System API 1.0.0

This API defines the minimal interface between the ReelData System & a RAS Feed Control System.

Interface Features

  • ReelData System can update appetite in Feed Control System for a tank feeder. * ReelData System can request the latest feeder state values from Feed Control System for a tank feeder. * The Feed Control System communicates changes as they occur to the ReelData System. * The Feed Control System acknowledges commands have been processed using the command acknowledgement system. * The Feed Control System uses a signed certificate to securely connect & communicate with the ReelData System.

Reading this document

This document is written from the perspective of the Feed Control System. PUB & SUB channels indicate how the Feed Control System would connect and interact with the MQTT interface used to communicate with the ReelData System.

ReelData and Feed Control communication use-cases

This section contains typical use-cases which illustrate communication between the ReelData system and the Feed Control System. See the 'Operations' section for the specifics of each interface shown in the diagrams below.

ReelData System sends appetite command for Tank 1 feeder

The diagram below illustrates the communication between the ReelData System and the Feed Control System when the ReelData System initiates a 'ReelData System - Appetite Command'.

diagram1 In response to the command, the Feed Control System submits a response on the Feed Control - Feeder Information Update and Feed Control - Appetite Command Acknowledgement channels. Once the feeder state with the new appetite is received from the Feed Control System, the ReelData System stores it in its database and uses it as the basis of future appetite requests.

Feed Control System notifies ReelData system of an Operator change

When a change occurs in the Feed Control System to the state of a tank feeder, the Feed Control System shall notify the ReelData System of the change with a Feed Control - Feeder Information Update message. Here are examples covering all of the changes which would result in an info message to the ReelData System:

  • An operator adjusts appetite in the Feed Control System.
  • An operator turns a feeder off or on in the Feed Control System.
  • The maximum or minimum appetite the feeder supports changes.
  • An operator changes the pellet type being used to feed the tank.

diagram2 This flow is identical for any of the scenarios identified above.

ReelData System requests information from Feed Control System

The diagram below illustrates the communication between the ReelData System and the Feed Control System when ReelData initiates a 'ReelData System - Request Feeder Information Command'.

diagram3 In response to the command, the Feed Control System submits a response on the Feed Control - Feeder Information Update and Feed Control - Request Feeder Information Acknowledgement channels. In this way, the ReelData System can reconcile its state with that of the Feed Control System.

API Specification

Servers

  • mqtt://<facility>.<company>.mqtt.reeldata.aimqttproduction

    An example mqtt connection for a production environment.

    This will be supplied by ReelData.

    Security:
    • X509:

      X509 certificate used by the Feed Control System to connect to the ReelData System. Allows access on specific '{environment}' paths.

  • mqtt://dev.reeldata.mqtt.reeldata.aimqttdevelopment

    A test MQTT server which can be developed against for validation.

    A certificate will be provided by ReelData to test.

    Security:
    • X509:

      X509 certificate used by the Feed Control System to connect to the ReelData System. Allows access on specific '{environment}' paths.

Operations

  • SUB /{environment}/feeder/{tankFeederId}/cmd/appetite

    ReelData System - Appetite Command

    The ReelData System commands a specific feeder to a new appetite value in the Feed Control System.

    tankFeederId
    required
    string
    <= 128 charactersuid: tankFeederId

    The tank feeder id is the unique identifier of the tank feeder in the underlying Feed Control System.

    May be any string less than 128 characters which uniquely identifies the tank feeder in the Feed Control System.

    environment
    required
    string
    uid: environment

    Identifies the environment.

    The environment will be provided at the same time as the x509 certificate required to connect to the MQTT broker.

    Accepts the following message:

    ReelData Appetite CommandappetiteCommand

    ReelData command sent to the Feed Control System to update the Appetite value.

    object

    Examples

  • SUB /{environment}/feeder/{tankFeederId}/cmd/info

    ReelData System - Request Feeder Information Command

    The ReelData System requests the state of the feeder from the Feed Control System. The response is then response expected on the 'server/{tankFeederId}/info' channel.

    tankFeederId
    required
    string
    <= 128 charactersuid: tankFeederId

    The tank feeder id is the unique identifier of the tank feeder in the underlying Feed Control System.

    May be any string less than 128 characters which uniquely identifies the tank feeder in the Feed Control System.

    environment
    required
    string
    uid: environment

    Identifies the environment.

    The environment will be provided at the same time as the x509 certificate required to connect to the MQTT broker.

    Accepts the following message:

    ReelData Info CommandinfoCommand

    ReelData command sent to the Feed Control System to retrieve the current feeder info.

    object

    Examples

  • PUB /{environment}/server/{tankFeederId}/info

    Feed Control - Feeder Information Update

    This channel is used by the Feed Control System to communicate changes to the ReelData System. Example events which the Feed Control System shall inform the ReelData System include:

    • If the ReelData System requests appetite change for a tank, the Feed Control System shall publish to the feeder's topic indicating the new state for the tank.
    • If an operator manually changes appetite for a tank in the Feed Control System, the Feed Control System shall publish to the feeder's topic indicating the new state for the tank.
    • If a feeder is turned off for a tank, the Feed Control System shall publish to the feeder's topic indicating the new state for the tank feeder. To summarized the above:

      If any value defined in the 'Feeder State Update Message' changes in the Feed Control System for a tank, the Feed Control System shall publish all values in the 'Feeder State Update Message' to the corresponding feeder topic.

    tankFeederId
    required
    string
    <= 128 charactersuid: tankFeederId

    The tank feeder id is the unique identifier of the tank feeder in the underlying Feed Control System.

    May be any string less than 128 characters which uniquely identifies the tank feeder in the Feed Control System.

    environment
    required
    string
    uid: environment

    Identifies the environment.

    The environment will be provided at the same time as the x509 certificate required to connect to the MQTT broker.

    Accepts the following message:

    Feed Control System Tank Feeder Update MessagefeederUpdate

    The Feed Control System informs the ReelData System of new tank feeder values whenever they change.

    object

    Examples

  • PUB /{environment}/server/{tankFeederId}/res/appetite

    Feed Control - Appetite Command Acknowledgement

    The Feed Control System publishes to this topic when a command has been applied against the feeder.

    tankFeederId
    required
    string
    <= 128 charactersuid: tankFeederId

    The tank feeder id is the unique identifier of the tank feeder in the underlying Feed Control System.

    May be any string less than 128 characters which uniquely identifies the tank feeder in the Feed Control System.

    environment
    required
    string
    uid: environment

    Identifies the environment.

    The environment will be provided at the same time as the x509 certificate required to connect to the MQTT broker.

    Accepts the following message:

    Feed Control System Command Acknowledgement MessagefeedControlCommandAck

    The command acknowledgement message is sent by the Feed Control System to the ReelData System when an info or appetite command has been applied against the feeder.

    object

    Examples

  • PUB /{environment}/server/{tankFeederId}/res/info

    Feed Control - Request Feeder Information Acknowledgement

    The Feed Control System publishes to this topic with the status of the "ReelData System requests feeder information" command.

    tankFeederId
    required
    string
    <= 128 charactersuid: tankFeederId

    The tank feeder id is the unique identifier of the tank feeder in the underlying Feed Control System.

    May be any string less than 128 characters which uniquely identifies the tank feeder in the Feed Control System.

    environment
    required
    string
    uid: environment

    Identifies the environment.

    The environment will be provided at the same time as the x509 certificate required to connect to the MQTT broker.

    Accepts the following message:

    Feed Control System Command Acknowledgement MessagefeedControlCommandAck

    The command acknowledgement message is sent by the Feed Control System to the ReelData System when an info or appetite command has been applied against the feeder.

    object

    Examples

Messages

  • #1ReelData Appetite CommandappetiteCommand

    ReelData command sent to the Feed Control System to update the Appetite value.

    object
  • #2ReelData Info CommandinfoCommand

    ReelData command sent to the Feed Control System to retrieve the current feeder info.

    object
  • #3Feed Control System Tank Feeder Update MessagefeederUpdate

    The Feed Control System informs the ReelData System of new tank feeder values whenever they change.

    object
  • #4Feed Control System Command Acknowledgement MessagefeedControlCommandAck

    The command acknowledgement message is sent by the Feed Control System to the ReelData System when an info or appetite command has been applied against the feeder.

    object

Schemas

  • requestId
    string
    format: uuiduid: requestId

    Request Id is used to uniquely identify a response or information update from an underlying Feed Control System to a previous request sent by the ReelData System.

    The Request Id returned in acknowledgements and information updates by the Feed Control System is expected to match what is provided in requests initiated by the ReelData System.

    The ReelData System will ignore this field in the case where a message from the Feed Control System contains 'FEED_CONTROL_INITIATED'.

    The request id is a uuidv4 string.

  • appetite
    number
    >= 0uid: appetite

    Appetite value the ReelData System has requested for the feeder.

    Note: "appetite" can be either an integer or a floating point number. This will be configured by ReelData according to your feeder's requirements.

  • source
    string
    uid: source

    The source of the Feeder State Update Message.

    • REELDATA_INFO_REQUEST indicates it was due to a request from the ReelData System for current feeder state.
    • REELDATA_APPETITE_REQUEST indicates it was due to an appetite adjustment request from the ReelData System.
    • FEED_CONTROL_INITIATED is used to report changes which are unrelated to any request from the ReelData System.
      Allowed values:
    • "REELDATA_INFO_REQUEST"
    • "REELDATA_APPETITE_REQUEST"
    • "FEED_CONTROL_INITIATED"
  • maximumPhysicalAppetite
    number
    >= 0uid: maximumPhysicalAppetite

    Maximum appetite the Feed Control System allows

  • minimumPhysicalAppetite
    number
    >= 0uid: minimumPhysicalAppetite

    Minimum appetite the Feed Control System allows

  • pelletType
    number
    uid: pelletType

    Selected feed pellet.
    Any string identifier may be used to identify the pellet type.

  • runStatus
    string
    uid: runStatus

    Run status for a particular tank feeder.
    Used by the ReelData System to know if a tank feeder is off or on.

      Allowed values:
    • "ON"
    • "OFF"
  • status
    string
    uid: status

    Status of ReelData command sent to the Feed Control System, after Feed Control System is done processing the command.

      Allowed values:
    • "SUCCESS"
    • "BAD_REQUEST"
    • "FEEDER_UNAVAILABLE"
    • "COMMAND_TIMEOUT_IN_QUEUE"
    • "CLIENT_INTERNAL_ERROR"