View source for Global Vehicle HUD

The '''Global Vehicle HUD (GVHUD)''' is a free, open-use HUD provided by the NTBI Group. Anyone can implement GVHUD compatibility into their vehicle and the GVHUD is available for free.

==Overview==
The GVHUD is a dynamically customizable HUD intended for use by vehicle manufacturers. Manufacturers can use the GVHUD to control different aspects of the vehicle without designing their own HUD.

The NTBI Group does not maintain a list of compatible vehicles. GVHUD-compatible products should clearly label themselves as such. The NTBI Group does not provide any warranty or support for third-party GVHUD implementations.

<big>[https://marketplace.secondlife.com/p/Global-Vehicle-HUD-Latest-Version-for-GVHUD-Compatible-Vehicles/20803267 '''Click here''' for the latest version of the GVHUD.]</big>

==End-User Instructions==
Wear the GVHUD by right clicking it in your inventory and selecting "Wear" or "Add". You can also attach it to a different HUD slot (default Top), but you will likely need to reposition it manually.

You can position the GVHUD as desired in both hidden and shown mode. When hidden or shown, the GVHUD will reposition itself to the position it was last placed in while in that mode.

The GVHUD layout includes three main sections - a set of per-vehicle customizable buttons, an LCD display with soft buttons, and HIDE and GSTR buttons, which hide the GVHUD and send a folder with gesture keybinds, respectively. The customizable buttons and LCD display layout is different for each vehicle; refer to your vehicle's owner's guide for details.

==Vehicle Manufacturer Instructions==
Vehicle manufacturers must implement the following API on their own; no support is provided.

All communication with the GVHUD is done via channel <code>47504750</code>.

The following commands can be sent from the vehicle to the GVHUD using llRegionSayTo to the avatar's UUID, or the HUD UUID if preferred:

* '''SYN'''
** Format: <code>SYN</code>
** Should be sent by the vehicle when the driver sits. Must only be sent to the driver's avatar UUID, otherwise crosstalk will occur. GVHUD will respond with '''CON'''.
* '''ACK'''
** Format: <code>ACK|[vehicle name]|[array of button ID numbers]|[array of button latch flags]|[array of button states]|[siren main prim UUID]|[siren reverb prim UUID]|[siren name]|[switch state]</code>
** Should be sent by the vehicle in response to '''CON'''. Vehicle should also send '''MNU''' immediately after, if desired.
** [vehicle name] is the name of the vehicle to display on the LCD, up to 22 characters.
** [array of button ID numbers] is a comma-separated list of button ID numbers from the table below. The array must be exactly 30 buttons, ordered from 8 left to right at the top (excluding buttons above the LCD), 8 left to right in the center, 8 left to right on the bottom, then 6 left to right above the LCD.
** [array of button latch flags] is a comma-separated list of button latch flags, either 0 for momentary or 1 for latched. The array must be exactly 30 buttons, organized the same as above.
** [array of button states] is a comma-separated list of button states, either 0 for off or 1 for on. The array must be exactly 30 buttons, organized the same as above.
** [siren main prim UUID] and [siren reverb prim UUID] are the prim UUIDs of the siren emitter prims. See below for details.
** [siren name] is the name of the currently installed siren. Possible sirens are: GT6500, GT20A, VR900, BF200, UG4000, SP700, GT4500, MP224, eM, PC9, MP224E, EURO1
** [switch state] is the state of the four-position switch, either 0, 1, 2, or 3.
* '''MNU'''
** Format: <code>MNU|[JSON menu data]</code>
** Should be sent by the vehicle immediately after '''ACK''' and can be sent whenever the vehicle wants to set up a new LCD soft button menu tree, if desired.
** [JSON menu data] is a JSON array of menu items, which are JSON objects. Each menu item has the following attributes:
*** "l": label to display for menu item, a string of up to 8 characters, wrapped onto 2 lines of 4 characters each. To skip a menu item on the display, use an empty label ("").
*** "sub" (optional): a JSON array of menu items. If specified, opens a new menu when this menu item is selected.
*** "act" (optional): an action to perform when this menu item is selected. Can be one of the following:
**** "back": Moves back to the previous menu, if a submenu.
**** "help": Opens GVHUD help URL.
** To close the menu, send a blank string ("") for [JSON menu data].
* '''TXT'''
** Format: <code>TXT|[row number]|[text]</code>
** Can be sent by the vehicle to render text on the LCD. The GVHUD must have sent '''RFR''' first to signal that the display is ready, otherwise commands will be dropped.
** [row number] is the row number, from 0 to 3, to render text on. If a menu is currently active, using row numbers 2 or 3 will close the menu.
** [text] is the text to render, up to 24 characters.
* '''MSG'''
** Format: <code>MSG|[text]</code>
** Can be sent by the vehicle to send a chat message to the HUD wearer.
* '''UPD'''
** Format: <code>UPD|[button index]|[button ID]|[state]</code>
** Can be sent by the vehicle to update a button state on the GVHUD. Note that no processing will be performed for this button, so '''BTN''' will not be sent.
** [button index] is the index of the button in the button arrays, 0 to 29. Alternatively, [button index] can be set to -1 to use [button ID] instead.
** [button ID] is the button ID from the table below. Can be used if the vehicle would prefer handling commands via the button ID instead of the button index, but is very slightly slower. If [button index] is not -1, [button ID] is ignored.
** [state] is 0 for off or 1 for on.
* '''SIS'''
** Format: <code>SIS|[siren name]</code>
** Can be sent by the vehicle to install a siren outside of '''ACK'''.
** [siren name] is the name of the newly installed siren; see '''ACK''' for a list of possible sirens.
* '''SSS'''
** Format: <code>SSS|[siren state]</code>
** Should be sent by the vehicle if another GVHUD sends '''SST''', or if the vehicle has activated a park kill feature.
** [siren state] should be the [siren state] string provided by '''SST'''. [siren state] can also be "off" (without quotes) if the vehicle has a park kill feature.
* '''SVU'''
** Format: <code>SWU|[switch state]</code>
** Should be sent by the vehicle if another GVHUD sends '''SWS'''.
** [switch state] should be the [switch state] integer provided by '''SWS'''.
* '''DIS'''
** Format: <code>DIS</code>
** Should be sent by the vehicle when the driver unsits.

The following commands will be sent by the GVHUD to the vehicle using llRegionSayTo to the prim UUID of the object that sent '''ACK''' unless otherwise specified:

* '''OPT'''
** Format: <code>OPT|[menu label]</code>
** Sent by the GVHUD when a menu item is selected. Sent on every selection, including when switching to a submenu.
** [menu label] is the label of the selected menu item.
* '''RFR'''
** Format: <code>RFR</code>
** Sent by the GVHUD when it is ready to accept '''TXT''' commands. Vehicle should start sending '''TXT''' commands once it receives '''RFR''' after '''CON'''.
* '''BTN'''
** Format: <code>BTN|[button index]|[button ID]|[state]</code>
** Sent by the GVHUD when a button is pressed or released.
** [button index] is the index of the button in the button arrays, 0 to 29.
** [button ID] is the button ID from the table below.
** [state] is 0 for off or 1 for on.
* '''GST'''
** Format: <code>GST|[command]</code>
** Sent by the GVHUD when a gesture hotkey is used.
** [command] can be one of the commands described in Gesture Controls below.
* '''SRN'''
** Format: <code>SRN|[sound UUID]</code>
** Sent by the GVHUD ''directly to the siren emitter prim specified by '''ACK''' only'' to cause it to play a siren sound.
** [sound UUID] is a sound to play, or NULL_KEY to stop sounds.
* '''SST'''
** Format: <code>SST|[siren state]</code>
** Sent by the GVHUD when the siren mode changed. If multiple GVHUDs are attached, the vehicle should send '''SSS''' to the other GVHUD.
** [siren state] is the state of the siren.
* '''SWS'''
** Format: <code>SWS|[switch state]</code>
** Sent by the GVHUD when the switch is moved. If multiple GVHUDs are attached, the vehicle should send '''SWU''' to the other GVHUD.
* '''CON'''
** Format: <code>CON</code>
** Sent by the GVHUD when it is attached/reset, or in response to '''SYN'''.

===Siren Interface===
If a siren is used, two prims must be designated as siren sound emitter prims. Their UUIDs should be detected and sent in '''ACK'''.

To reduce latency, the GVHUD sends '''SRN''' commands directly to the prims designated by '''ACK'''. Each prim must listen for '''SRN''' independently of the script that handles other GVHUD communication, and should play siren sounds as sent by the GVHUD. A sample script is below, which should be placed in each of the prims designated as siren emitter prims:

 default
 {
     state_entry()
     {
         llListen(47504750, "", "", "");
     }
     listen(integer channel, string name, key id, string message)
     {
         if (llGetSubString(message, 0, 3) == "SRN|" && id == hud_uuid)
         {
             string uuid = llGetSubString(message, 4, -1);
             if (uuid == NULL_KEY) llStopSound();
             else llLoopSound(uuid, 1.0);
         }
     }
 }

Sound emitter scripts must verify that the object that sent the '''SRN''' command is the connected GVHUD. This script snippet does not define <code>hud_uuid</code>; it must be set when the script that controls GVHUD communication sends '''ACK''' so that the emitter knows the UUID of the connected GVHUD.

===Gesture Controls===
The gestures provided in the GVHUD send the following internal commands:

* '''F2''': "ZF2", resizes GVHUD.
* '''F3''': "ZF3", toggles axle lock (button ID 28), if equipped, otherwise ignored.
* '''F4''': "ZF4", cycles through hands-free siren tones, if eqipped, otherwise ignored.
* '''F5''': "ZF5", moves switch to position 0.
* '''F6''': "ZF6", moves switch to position 1.
* '''F7''': "ZF7", moves switch to position 2.
* '''F8''': "ZF8", moves switch to position 3.
* '''Ctrl + Left''': "ZCA", toggles turn L (button ID 24), if equipped, otherwise ignored.
* '''Ctrl + Right''': "ZCD", toggles turn L (button ID 29), if equipped, otherwise ignored.
* '''Ctrl + Down''': "ZCS", toggles hazards (button ID 25), if equipped, otherwise ignored.
* '''H''': "ZZH", horn tap, sends <code>GST|HORN</code>.
* '''L''': "ZZL", toggles cycle headlights (button ID 26), if equipped, otherwise ignored.
* '''K''': "ZZK", high beams flash, sends <code>GST|BRIGHT</code>.
* '''I''': "ZZI", toggles key (button ID 7), if equipped, otherwise ignored.
* '''O''': "ZZO", get out, sends <code>GST|OUT</code>.
* '''Space''': "ZZ_", handbrake, sends <code>GST|BRAKE</code>.
* '''1''': "ZZ1", camera 1, sends <code>GST|CAM1</code>.
* '''2''': "ZZ2", camera 2, sends <code>GST|CAM2</code>.
* '''3''': "ZZ3", camera 3, sends <code>GST|CAM3</code>.
* '''4''': "ZZ4", camera 4, sends <code>GST|CAM4</code>.
* '''5''': "ZZ5", camera 5, sends <code>GST|CAM5</code>.
* '''6''': "ZZ6", camera 6, sends <code>GST|CAM6</code>.

===Button IDs===
The following is a list of available button IDs.

This list can be expanded by the NTBI Group without a GVHUD update. If you have a button label you would like to be integrated into the GVHUD's available buttons, contact Nelson Jenkins.

{| class="wikitable"
|-
! ID || Description || ID || Description || ID || Description || ID || Description
|-
| -10 || Siren Wail* || -11 || Siren Yelp* || -12 || Siren Priority* || -13 || Siren Manual*
|-
| -14 || Siren Horn* || -1 || Blank || || || || 
|-
| 0 || LIGHT BAR (Red) || 1 || STRB (Red) || 2 || TKDN FLASH (Red) || 3 || TAKE DOWN (Red)
|-
| 4 || FLOOD (Red) || 5 || CRZ (Red) || 6 || (Reserved) || 7 || Key (Green)
|-
| 8 || HIDE AWAY (Red) || 9 || WIG WAG (Red) || 10 || Arrow (Red) || 11 || Siren Wail*
|-
| 12 || Siren Yelp* || 13 || Siren Priority* || 14 || Siren Manual* || 15 || Siren Horn*
|-
| 16 || AUX 1 || 17 || AUX 2 || 18 || AUX 3 || 19 || CUT F (Red)
|-
| 20 || CUT R (Red) || 21 || (Reserved) || 22 || (Reserved) || 23 || (Reserved)
|-
| 24 || Turn Sig L || 25 || Cycle Headlights || 26 || Hazard Flashers || 27 || Horn
|-
| 28 || Axle Lock || 29 || Turn Sig R || || || || 
|}

<nowiki>*</nowiki> Use negative button IDs for GVHUD to handle the siren. The GVHUD will automatically pick the correct buttons to show, will only allow one on at a time, and will send siren commands directly to the prims specified in SSU. Use positive button IDs for sirens only if you want them to send BTN commands and not be connected together.