KellyFuel/Creator Instructions
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.
Contents
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. The pump uses llRegionSayTo to send commands to a specific aircraft. It is recommended that the aircraft also reply using llRegionSayTo to the object from which it received the request.
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 pump will typically send multiple add commands over timed intervals to simulate the time needed to refuel. 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 detects when fueling is complete.
Example: The left fuel tank (named "left") in your Cessna 172 holds a maximum of 21.5 gallons, and currently contains 18 gallons of fuel. The following would be the expected exchange between the pumps and the aircraft:
Pump: @refuel add left 10 100ll
Aircraft: @ack add 10 3.5
The pump command requests to add 10 gallons of 100ll fuel to the left tank. The reply from the aircraft acknowledges 10 gallons was requested, but only 3.5 gallons could be added to the tank (the remaining capacity of the tank).
1.4.1 Fuel Taint
The fuel-type parameter of the add query can optionally be used to implement handling of misfueling in your aircraft. If your aircraft has a piston (jet) engine and you receive an add query with a fuel type other 100ll (jeta), then you can mark an internal flag in your aircraft to indicate the fuel is tainted. You are free to implement any symptoms of misfueling you choose including failure to start, or failure of engine after a time interval (in RL, engine failure from misfueling often occurs after takeoff once all the clean fuel in the fuel lines have been consumed). You are also free to implement a method of clearing the taint flag (e.g., by draining the tank).
2 Programming Fuel Port Positions
This section describes how to program the fuel pump for use with your aircraft. The RP aspects of refueling can be greatly enhanced when the pump knows what fuel tanks your aircraft has, and the location of the filler ports. The creator of an aircraft and their designated assistant has the ability to use the port configuration options of the KellyFuel pump. These options allow you to Add, Edit or Remove a tank/port from your aircraft.
To program an aircraft, begin by rezing your aircraft near a KellyFuel 3.0 pump. Click the pump and select the aircraft by object name (or by tail number if you are using the Shergood registration system). If your aircraft is not detected, you can add it yourself on the Shergood web site at https://shergoodaviation.com/aircraft.php , or if you are a new creator contact Kelly Shergood to be added as a creator on the site.
After connecting the aircraft, click the pump to bring up the main menu. If you have admin privileges for the aircraft, in addition to the currently configured tank names, you should see a button labeled "*Edit" (see Figure 1). This option is used for editing the aircraft type information on the servers. The prompt part of the menu includes information about the selected aircraft, its type, and the fuel system designated for that type. An example of the edit menu is shown in Figure 2. However, the "*SetPortPos" and "*DelPort" options will appear only if a specific port has first been selected from the main menu.
2.1 Adding A Port
To add a port/tank to an aircraft use the "AddPort" option. This will bring up a text box into which you can type the name of a tank/port on your aircraft. If the aircraft has only one tank, it is recommended that you used the name "main" for the tank.
The Setup tool folder contains the following tools:
- sa-kf-ground-setup - Indicates the position of the ground wire clip
- sa-kf-nozzle-setup - Indicates the position of a standard gravity fed nozzle
- sa-kf-pressNozzle-setup - Indicates the position of a pressure refueling nozzle
Once you have added a fuel tank, you can use either the sa-kf-nozzle-setup or the sa-kf-pressNozzle-setup tool to indicate where on your aircraft a refueling nozzle should be positioned. Use the sa-kf-nozzle-setup if it is a standard gravity-fed tank, and use sa-kf-pressNozzle-setup if it is a high-speed pressure refueling port (normally only used on large aircraft).
