Difference between revisions of "KellyFuel/Creator Instructions"

From
Jump to: navigation, search
(Chat Commands)
Line 1: Line 1:
 
This section is intended for aircraft creators who wish to use KellyFuel in their build.  KellyFuel operates over a channel to send and receive commands to your helicopter.  You can configure a private channel to use for this purpose.  KellyFuel identifies the aircraft being refueled by checking the creator name and the object name against a database.  Since users often rename the aircraft, partial matching is used on the object name looking for specific key parts of the name.  As a creator, you can edit the object name matching criteria for your aircraft on the SA website.
 
This section is intended for aircraft creators who wish to use KellyFuel in their build.  KellyFuel operates over a channel to send and receive commands to your helicopter.  You can configure a private channel to use for this purpose.  KellyFuel identifies the aircraft being refueled by checking the creator name and the object name against a database.  Since users often rename the aircraft, partial matching is used on the object name looking for specific key parts of the name.  As a creator, you can edit the object name matching criteria for your aircraft on the SA website.
  
 +
== Chat Commands ==
  
 +
This section describes the basic commands sent by the pump and the expected replies from the aircraft.  All communication is on your configured channel.  Aircraft creators may optionally choose to open the chat listener for fuel only then the fuel cap on their aircraft is removed to limit the number of open channels.
  
== Chat Commands ==
+
=== Aircraft Tank Query ===
  
 
Pump: <tt>@refuel check</tt><br>
 
Pump: <tt>@refuel check</tt><br>
Reply: <tt>@ack 2 check <i>cur-level</i> <i>max-level</i> <i>tank name</i></tt>
+
Aircraft: <tt>@ack 2 check <i>cur-level</i> <i>max-level</i> <i>tank-name</i></tt>
 +
 
 +
This command is used to query which tanks on an aircraft are ready for fueling.  In the aircraft response, "2" is the protocol-number, <i>cur-level</i> is the current number of gallons in a tank, <i>max-level</i> is the maximum number of gallons in the tank, and <i>tank-name</i> is the name of the tank.  If the aircraft has only one tank, the name "main" should be used for the tank.  If the aircraft has multiple tanks, an "@ack" command should be sent for each tank.
 +
 
 +
=== Fuel Level Query ===
  
 
Pump: <tt>@refuel look <i>name</i></tt></br>
 
Pump: <tt>@refuel look <i>name</i></tt></br>
Reply: <tt>@ack look <i>cur-level</i> <i>max-level</i> <i>tank name</i> <i>taint-status</i>
+
Aircraft: <tt>@ack look <i>cur-level</i> <i>max-level</i> <i>tank-name</i> <i>taint-status</i>
 +
 
 +
This command is used to "look" into a tank.  It is similar to the "check" command except that it includes a specific tank name in the query.  The response elements are the same as the "check" command but includes and additional <i>taint-status</i> value.  The taint status should be 0 if fuel in that tank is clean, and 1 if it is tainted.  See the discussion on the "add" command for information on fuel tainting.
 +
 
 +
=== Fill Tank to Full ===
  
 
Pump: <tt>@refuel full</tt><br>
 
Pump: <tt>@refuel full</tt><br>
Reply: <tt>@ack full</tt>
+
Aircraft: <tt>@ack full</tt>
 +
 
 +
This command requests that all tanks be completely filled.  This command is sent when a user chooses "Auto Fill" from the menu bypassing the normal RP elements.
 +
 
 +
=== Add Fuel to Tank ===
 +
 
 +
Pump: <tt>@refuel add <i>tank-name</i> <i>amount</i> <i>type</i></tt></br>
 +
Aircraft: <tt>@ack add <i>amount</i> <i>actual</i></tt>
 +
 
 +
This command incrementally adds fuel to a tank.  The query specifies the name of the tank, the number of gallons to add, and a fuel type.  Note the fuel type may be omitted by pumps prior to Version 3.0.  The fuel type can be one of:
 +
 
 +
* 100ll - Aviation fuel used by piston aircraft
 +
* jeta - Fuel for most jet and turbo-prop aircraft
 +
* fueloil - Fuel used by certain vintage/steampunk aircraft
 +
 
 +
The aircraft response should include the amount requested to be added, and the actual amount added to the tank.  If the amount requested to be added is more than the remaining capacity of the tank, the <i>actual</i> value should be the remaining capacity.  If the tank is full, 0 should be returned for <i>actual</i>.  It is important to return accurate values as detecting when <i>actual</i> is less than <i>requested</i> is how the pump detected when fueling is complete.
  
Pump: <tt>@refuel add <i>name</i> <i>amount</i> <i>type</i></tt></br>
+
==== Fuel Taint ====
Reply: <tt>@ack add <i>amount</i> <i>actual</i></tt>
 

Revision as of 00:46, 27 August 2022

This section is intended for aircraft creators who wish to use KellyFuel in their build. KellyFuel operates over a channel to send and receive commands to your helicopter. You can configure a private channel to use for this purpose. KellyFuel identifies the aircraft being refueled by checking the creator name and the object name against a database. Since users often rename the aircraft, partial matching is used on the object name looking for specific key parts of the name. As a creator, you can edit the object name matching criteria for your aircraft on the SA website.

1 Chat Commands

This section describes the basic commands sent by the pump and the expected replies from the aircraft. All communication is on your configured channel. Aircraft creators may optionally choose to open the chat listener for fuel only then the fuel cap on their aircraft is removed to limit the number of open channels.

1.1 Aircraft Tank Query

Pump: @refuel check
Aircraft: @ack 2 check cur-level max-level tank-name

This command is used to query which tanks on an aircraft are ready for fueling. In the aircraft response, "2" is the protocol-number, cur-level is the current number of gallons in a tank, max-level is the maximum number of gallons in the tank, and tank-name is the name of the tank. If the aircraft has only one tank, the name "main" should be used for the tank. If the aircraft has multiple tanks, an "@ack" command should be sent for each tank.

1.2 Fuel Level Query

Pump: @refuel look name
Aircraft: @ack look cur-level max-level tank-name taint-status

This command is used to "look" into a tank. It is similar to the "check" command except that it includes a specific tank name in the query. The response elements are the same as the "check" command but includes and additional taint-status value. The taint status should be 0 if fuel in that tank is clean, and 1 if it is tainted. See the discussion on the "add" command for information on fuel tainting.

1.3 Fill Tank to Full

Pump: @refuel full
Aircraft: @ack full

This command requests that all tanks be completely filled. This command is sent when a user chooses "Auto Fill" from the menu bypassing the normal RP elements.

1.4 Add Fuel to Tank

Pump: @refuel add tank-name amount type
Aircraft: @ack add amount actual

This command incrementally adds fuel to a tank. The query specifies the name of the tank, the number of gallons to add, and a fuel type. Note the fuel type may be omitted by pumps prior to Version 3.0. The fuel type can be one of:

  • 100ll - Aviation fuel used by piston aircraft
  • jeta - Fuel for most jet and turbo-prop aircraft
  • fueloil - Fuel used by certain vintage/steampunk aircraft

The aircraft response should include the amount requested to be added, and the actual amount added to the tank. If the amount requested to be added is more than the remaining capacity of the tank, the actual value should be the remaining capacity. If the tank is full, 0 should be returned for actual. It is important to return accurate values as detecting when actual is less than requested is how the pump detected when fueling is complete.

1.4.1 Fuel Taint