Difference between pages "InfoCenter" and "Global Mod Link System"

(Difference between pages)
m
 
m
 
Line 1: Line 1:
−
{{ infobox product
+
The '''Global Mod Link System (GMLS)''' is a free, full-permission script system provided by the NTBI Group. Anyone can implement GMLS into their modifiable vehicle, and anyone can build mods that automatically position themselves when linked to a GMLS-compatible vehicle.
−
| title            = InfoCenter
 
−
| image            = [[File:replaceme.jpg|200px|center]]
 
−
| caption          = InfoCenter Display Kit vendor image.
 
−
| inventor        = [[Nelson Jenkins]], [[SLI Komarov]]
 
−
| launch year      = 2008, upgraded in 2014
 
−
| company          = [[Gentek]]
 
−
| available        = Marketplace & In-World
 
−
| url              = '''[https://marketplace.secondlife.com/p/InfoCenter-Display-Kit-Four-Electronic-Text-Display-Sign-Models/6579929 InfoCenter Display Kit]'''<br>'''[https://marketplace.secondlife.com/p/InfoCenter-Mobile-Trailer-Mounted-Electronic-Text-Display-Sign/6579901 InfoCenter Mobile]'''
 
−
}}
 
  
−
The '''InfoCenter''' is a series of electronic text display signs (Personal, Notice, Highway, Matrix, and Mobile) sold by [[Gentek]]. They are designed for transportation & commercial purposes, although have been creatively used for a wide variety of applications. They are all web-controllable and include an API for scripters and web developers.
+
==Overview==
 +
GMLS is a set of full-permissions scripts. It is intended for use in modifiable vehicles to simplify the installation of prebuilt modifications. For example, the NTBI Factory Lightbar Package uses GMLS to automatically position lightbars when linked to compatible vehicles.
  
−
This page covers the InfoCenter Series v3 and above. Because of the complexity in the new system and licensing restrictions, v3 is not a free update. For older versions, visit these pages: [[InfoCenter Mobile|Mobile]], [[InfoCenter Highway|Highway]], or [[InfoCenter Personal|Personal]]
+
Aftermarket modification manufacturers can set up GMLS by linking a copy of the modification to the desired vehicle and using the Calibration Tool to set up the Alignment Tool. Then, when an end-user links the modification to a compatible vehicle, the modification will reposition itself (and, if necessary, rescale itself) automatically. GMLS can also unlink certain prims from the vehicle for factory prim replacements.
  
−
==Models==
+
GMLS comes with three scripts:
−
The InfoCenter is made up of two separate products - the InfoCenter Display Kit, and the InfoCenter Mobile.
 
  
−
===InfoCenter Display Kit===
+
* '''NTBI GMLS Alignment Tool''' - Inserted into aftermarket modifications and edited by the modification manufacturer to program alignment positions and other options.
−
The Display Kit includes the following models (in both standard and Duo variants, Duo typically doubling both the number of lines and characters per line, effectively quadrupling capacity):
+
* '''NTBI GMLS Calibration Tool''' - Used to calibrate alignment positions; outputs alignment data to be placed in the Alignment Tool.
−
* '''InfoCenter Personal''' - 16 x 1 (2 LI) or 32 x 2 (5 LI) characters. Ideal for general commercial use, and includes a variety of animated graphics for stores.
+
* '''NTBI GMLS Vehicle Sample Script''' - Inserted into vehicles and edited by the vehicle manufacturer to define vehicle information for use by modifications.
−
* '''InfoCenter Notice''' - 16 x 7 (8 LI) or 32 x 14 (29 LI) characters. The highest-capacity model, ideal for news & information. Also includes graphics for commercial & industrial purposes.
 
−
* '''InfoCenter Highway''' - 16 x 3 (4 LI) or 32 x 6 (13 LI) characters. Best suited for overhead gantry installations on roads, but can be used for walkway or general commercial applications.
 
−
* '''InfoCenter Matrix''' - 4 x 2 (1 LI) or 8 x 5 (3 LI) characters. A road sign display with many graphics for lane control, variable speed limits, hazard warning, detours, turn restrictions, and more.
 
−
All models, excluding the Highway, have a toggleable mounting bracket. All models are modifiable (scripts excluded) and can be resized or linked (with the caveat that they cannot be linked together).
 
  
−
===InfoCenter Mobile===
+
The NTBI Group does not maintain a list of compatible vehicles or modifications. GMLS-compatible products should clearly label themselves as such. The NTBI Group does not provide any warranty for third-party GMLS implementations.
−
The Mobile model is used for construction & road closures. 8 x 3 characters (3 LI) - the Mobile does not have a Duo variant. It is a trailer unit which can be rotated for the optimum viewing angle. It also has two trailer colors (grey & orange) and the display unit can be resized to three different sizes for different use cases. Unlike other models, the InfoCenter Mobile is not modifiable.
 
  
−
Because of the Mobile's long-lasting popularity over other models, we sell it separately to reduce costs for those just interested in this model. Besides the features above, the Mobile is technically identical to all other models - it is web controllable and uses the same API.
+
<big>[https://marketplace.secondlife.com/p/GMLS-Development-Kit-Tools-for-Integrating-the-Global-Mod-Link-System/20803262 '''Click here''' for the GMLS developer kit.]</big>
  
−
==Setup & Use==
+
==End-User Instructions==
−
InfoCenter devices are ready for use out of the box. You can control some cosmetic options described above, but once they are rezzed, they can be set immediately.
+
Refer to your vehicle's owner's guide for instructions on how to install GMLS-compatible equipment.
  
−
All InfoCenter devices are accessible through the [http://ntbigroup.com/gentek/infocenter/ InfoCenter Manager.] If you access the Manager directly, you will have to log in - you can avoid this by clicking a sign and selecting ''Web Control''. (This will also highlight the selected sign in the manager.)
+
If the owner's guide does not provide instructions, the following is a general checklist for installing GMLS-compatible modifications:
  
−
If you have not created an NTBI Group account before, you will be prompted to enter a password - do not use your SL password for this! Then, in the future, you can log in to the NTBI Group website (including the InfoCenter Manager) without even being in-world.
+
# Ensure that the vehicle is turned off, including any lighting or other components that may change any attributes while installing the modification.
 +
# Take a copy of your vehicle as-is. Modifications may cause damage or unlink prims accidentally. Save a copy now in case this happens!
 +
# Rez the modification near your vehicle.
 +
# Right click the modification and select "Edit".
 +
# With the Edit window open, hold your SHIFT key and left click the vehicle. This should select both objects at once. Make sure you select the vehicle last.
 +
# Press your CTRL + L keys, or click the "Link" button in the Edit window.
 +
# If prompted, confirm that you want to link the two objects together.
 +
# When linked, the modification should automatically position itself to the recommended position and resize if necessary.
 +
# If prompted, grant link permissions. This may unlink some prims. Make sure to delete them after.
 +
# If desired, you may usually move the equipment once linked.
  
−
===Setting a Message===
+
If a modification does not use GMLS, is not compatible with your vehicle's GMLS system, or returns an error when linking using the above procedure, follow steps 1 through 6, then manually reposition the modification as needed.
−
You can set any of your InfoCenter devices from the InfoCenter Manager. Click the ''Set'' button, and you will be shown the message designer interface.
 
  
−
Messages are made up of slides. Each slide can either be a text slide or a graphic slide, and can be set to display for generally any length of time you want. Slides are displayed sequentially and loop when completed.
+
==Aftermarket Modification Manufacturer Instructions==
 +
Get the Alignment Tool and Calibration Tool from the [https://marketplace.secondlife.com/p/GMLS-Development-Kit-Tools-for-Integrating-the-Global-Mod-Link-System/20803262 GMLS developer kit.]
  
−
The grey number next to the model name for the device you are setting is the maximum number of slides - this is dependent on the capacity of the display, so smaller displays can handle more slides (up to 60). Some very high capacity devices (such as the Notice Duo) can only handle a few slides.
+
Before continuing, make sure your mod is finished. Do not continue until you are sure you do not need to make any changes to your object.
  
−
When you open the message designer, the message currently displayed on that device will be shown, so you can edit it if you wish. By default, it is a single blank slide.
+
# Make a two copies of your object. One will be used for calibration. The other will be distributed to your end-users.
 +
# Place the "NTBI GMLS Alignment Tool" script in the distribution object (the one you will keep).
 +
# Place the "NTBI GMLS Calibration Tool" script in the calibration object (the one you will link, then delete).
  
−
* To add a text slide, type your message into the text cell input area. By default, the Amber color is used, but you can click any color in the palette below to select that color. Any new characters you type will then be in that color. When you're finished, click the ''Add Text'' button to add it to the slides.
+
For each vehicle you want your object to be compatible with:
−
** Because of Javascript limitations, you must release each key before typing the next one, otherwise it won't register - type slowly and carefully!
 
−
** Some characters are not permitted as text. If that is the case, they will not be entered.
 
−
** For a full box character, like older InfoCenter models, use the ^ (caret) character. (This will not be shown on the website - it will only appear correctly in-world.)
 
−
* To add a graphic slide, select a graphic from the dropdown. A preview will appear above it. To add the graphic, click ''Add Graphic''.
 
−
* To move slides around or delete them, click the icons next to them. Keep in mind that by default, a blank slide is included as the first slide - you may want to remove it.
 
−
* To change the time that a slide is shown, click ''Change'' and type in a new time (in seconds), then click ''Save''. Some high-capacity devices require longer slide times.
 
  
−
When you're finished, click ''Send To This Device''. The message will be sent and displayed immediately in-world. For information on how the ''Send To Entire Group'' button works, read '''Using Groups''' below.
+
# Make a new copy of the calibration object. It should have the "NTBI GMLS Calibration Tool" script already in it.
 +
# Rez the vehicle. Make sure it is the original size!
 +
# Position the calibration object on the vehicle, exactly where you want it to be once installed by the end-user.
 +
# Link the calibration object to the vehicle.
 +
# Copy the script snippet line sent to local chat.
 +
# Open the "NTBI GMLS Alignment Tool" script in the distribution object.
 +
# Paste the script snippet line between the two marked lines at the top of the script. NOTE: The first part of each line is the GMLS ID of the vehicle you have calibrated to. If you see a line with the same GMLS ID, you have already calibrated to that vehicle, and only the first instance of that vehicle will be used.
 +
# Save the "NTBI GMLS Alignment Tool" script.
  
−
===Using Templates===
+
Once finished, delete any calibration objects and vehicles.
−
Templates are a way to easily save and recall messages. Say, for example, that you have 3 different messages you plan on displaying, but only one at a time, and you don't want to retype them every time. Templates allow you to save the message and load it later on that device (or any same-model device).
 
  
−
* To save a template, design the message that you want to display, then type in a name above the ''Save As Template'' button, then click the button. If you already have a template with that name, it will be overwritten, so check first.
+
If you want the root prim of the object to retain its physics type when linked to the vehicle, change root_no_physics to FALSE. (By default, the root prim of this object will be set to physics type "none" and the physics types of child prims will remain the same.)
−
* To load a template, click the dropdown to the right and select the template you want, then click ''Load''. To permanently delete a template, click ''Delete'' instead.
 
  
−
===Using Groups===
+
If you want to have the GMLS script automatically unlink prims, list their names in the remove_prims list. If you do this, you can also change remove_move_dist to change the distance unlinked prims will move up, and you can change remove_recolor to FALSE if you do not want unlinked prims to be recolored bright red for visibility.
−
Groups are an easy way to control multiple devices at once. Devices can only belong to a single group at a time, but you can have multiple groups. Each group can only support one specific model.
 
  
−
* To add a device to a group, click the ''Group'' button, then enter the name of the group you want to add it to. If the group doesn't exist, it will be created. If it does, the device will simply be added to the group.
+
If you do not want the object to be set to temporary when unlinking prims in the remove_prims list so that they automatically delete themselves, change make_temp to FALSE.
−
* To remove a device from a group, click the ''Group'' button, delete the text in the textbox, and then click ''OK''. This will remove it from the group. If the group no longer has any members, it will be hidden, but not technically deleted - if you recreate that group with the same name, the API key will be retained. (More information on this is in the API section.)
 
−
* To rename a group, click the ''Rename'' button next to it, then enter a new group name. This will rename it without changing the API key, and all devices will remain in the group under the new name.
 
−
* To set a message on an entire group, begin by setting a message on a single group member. When you're ready, click ''Send To Entire Group''. This will send the message to all group members.
 
  
−
===Renaming & Deleting Devices===
+
When finished, make sure you test your modification on each compatible vehicle to make sure it works correctly.
−
When your device is first rezzed, it will be named "Unnamed" followed by a number. Not only is this not descriptive, but it is a bit dangerous - if your display is reset for any reason, it will lose its old name and API key. To rename it, simply click the ''Rename'' button and enter a new name. You can also rename it from in-world using the ''Set Disp ID'' option.
 
  
−
If your device disappears in-world, it will remain in the InfoCenter Manager. This is intended - it's to prevent accidentally deleting the device if the region is temporarily offline or there is a communication error. You can delete devices from the InfoCenter Manager by clicking ''Delete''. This will not delete it in-world - it will only disappear from the website and lose its API key. If you delete a display while it is still in-world and online, you will get a notification in-world.
+
===API===
 +
The Alignment Tool and vehicle script send the following link messages that can be used to trigger additional scripts in your modification:
  
−
Sometimes, you may have several devices which no longer exist, but you don't want to delete them individually. To "flush" non-responsive devices, click the link at the very bottom of the page. This will individually check each device and, if it does not respond, it will be deleted automatically. Note that if a region is offline or very laggy, devices in it may be deleted without warning, so make sure all regions are OK before doing this.
+
* <code>GMLS_REQUEST</code>
 +
** Sent by Alignment Tool once linked. Vehicle responds with <code>GMLS_ID</code> if compatible. You can also send this manually once the GMLS script is finished if you need any information from <code>GMLS_ID</code>.
 +
* <code>GMLS_ID</code>
 +
** '''Key''': [gmls_id]|[root scale]|[additional information]
 +
** Sent by vehicle in response to <code>GMLS_REQUEST</code>. Note that [root scale] is not the ''size'' of the root prim of the vehicle, but rather the ratio of the current size of the root to the original size of the root. For example, [root scale] on a vehicle that was upsized to twice its original size would be <2.0, 2.0, 2.0> regardless of its actual size.
 +
* <code>GMLS_SUCCESS</code>
 +
** Sent by Alignment Tool if the GMLS operation completed successfully and it is now safe to perform any configuration changes or whatever else on the newly linked-to vehicle.
 +
* <code>GMLS_FAIL</code>
 +
** Sent by Alignment Tool if the GMLS operation failed either because the object the modification was just linked to is not GMLS-compatible or the vehicle has a gmls_id that the modification was not calibrated for.
 +
* <code>GMLS_CANCEL</code>
 +
** Sent by Alignment Tool if the GMLS operation was cancelled by the user.
  
−
==Updates & Release Notes==
+
==Vehicle Manufacturer Instructions==
−
You can update any InfoCenter product by rezzing it directly from your inventory (each one has an updater script which auto-deletes on first rez, so rezzing a used copy will not work).
+
Get the Alignment Tool and Calibration Tool from the [https://marketplace.secondlife.com/p/GMLS-Development-Kit-Tools-for-Integrating-the-Global-Mod-Link-System/20803262 GMLS developer kit.]
−
* '''v3.1'''
 
−
** Added chat API.
 
−
* '''v3.0'''
 
−
** Upgraded public release.
 
−
** Rewrote everything, so old release notes are irrelevant.
 
  
−
==API Documentation==
+
Before continuing, make sure your vehicle's root prim will not be resized before it is distributed. Do not continue until the root prim is finalized.
−
If you aren't planning on using the API as a scripter, you don't need to read this part - everything below this line is about the API. If you are, you'll be surprised how much you can do through the API.
 
  
−
The InfoCenter API allows you to control any sign from anywhere in-world or from any web server. You can set messages, change groups, rename things, and query for information. All you need is the API key for the display or group you want to control - you can even use API keys for displays you do not own.
+
# Place the "NTBI GMLS Vehicle Sample Script" script in the vehicle. If you prefer, you can also integrate this script into another script in the vehicle to save memory.
 +
# Edit the gmls_id string. You can use any string as long as it does not include the pipe ("|") character, but it should be limited to alphanumeric characters, underscores ("_"), and be up to 32 characters. The gmls_id must be unique for every vehicle that has a different layout of potential modification positions. For example, use different IDs for 2DR and 4DR variations of the same vehicle.
 +
# Edit the gmls_default_root_size vector to be the size of the root prim of the vehicle. On most viewers, you can get this value by opening the Edit window, going to the Object tab, and pushing the "C" button next to Size. WARNING: This is not optional. Failure to set this value will cause GMLS modifications to align improperly.
 +
# Save the "NTBI GMLS Vehicle Sample Script" script. If kept separate, you can [http://wiki.secondlife.com/wiki/LlSetMemoryLimit limit the memory used by the script] if you prefer.
  
−
That said, '''keep your API keys private'''! If anyone else gets a copy of your API key, they can control your device without you knowing. (Of course, you can give API keys out to trusted people if you want them to control your devices.) If this happens, you can reset your API key by clicking the ''Refresh'' link next to it - but note that you can't set your own API key, and any scripts that use the old key will no longer work.
+
Perform this procedure for each vehicle variation. Once finished, it is a good idea to test the GMLS settings by creating a simple object and following the Aftermarket Modification Manufacturer Instructions.
  
−
Unlike the InfoCenter API from v2, the v3 API is HTTP-based, and the "server" can be deleted or do other things - the API can send entire messages, not just single frames, and they will be cycled locally on the device. Additionally, messages sent through the API are visible from the InfoCenter Manager, and can be edited manually. As stated above, the API object can be anywhere in-world, and no longer has to be in the same region - scripters with knowledge of PHP or other web server languages can also use the API by adapting the commands shown here (this will not be documented, so it's a DIY job). If you prefer a chat-based API, scroll to the bottom of the page.
+
==Changelog==
−
 
+
Rev. 2
−
All commands return some form of usable repsonse. Invalid request types and internal errors will return <code>ERROR</code>. Although it is recommended to capture the request key and handle a response accordingly, it is not absolutely required. More information on LSL's <code>http_response</code> event is [http://wiki.secondlife.com/wiki/Http_response here.]
+
* Added make_temp option.
−
 
+
* Changed unlinking parts procedure so that unlinked prims are set to temporary if make_temp is enabled.
−
===Setting a Message===
+
Rev. 1
−
You can set a message using the <code>set</code> request:
+
* Added GMLS_SUCCESS, GMLS_FAIL, and GMLS_CANCEL link messages.
−
 
+
* Fixed erroring out and refusing to reposition if linked before permissions have been granted.
−
<code>
+
* Fixed unlinking parts check running before checking if vehicle is compatible in the first place.
−
llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=set&k=apikey</nowiki>",[HTTP_METHOD,"PUT"],"content");
+
* Fixed crosstalk when multiple GMLS modifications are rezzed at once.
−
</code>
+
* Improved vehicle detection in slow regions by extending identification time from 2 seconds to 5 seconds.
−
 
+
Rev. 0
−
Replace ''apikey'' with the API key for the device or group you want to use, and replace ''content'' as described below. (This command will work for both devices and groups interchangeably.)
+
* Initial public release.
−
 
 
−
This request can return the following in the <code>http_response</code> event:
 
−
 
 
−
* <code>OK</code> - the message was sent to all devices succesfully
 
−
* <code>GROUPFAIL</code> - the message was sent to some devices in the group, but some (not all) did not respond
 
−
* <code>FAIL</code> - the message was not sent to any devices because none responded
 
−
* <code>FORMAT-SEPARATOR</code> - your content string is not separated by <code>#$</code>
 
−
* <code>FORMAT-SLIDES</code> - your slide data and slide time lists are not the same length, or you sent more slides than the selected device/group can handle
 
−
* <code>FORMAT-DATA</code> - one of your slide data strings is not the correct length
 
−
* <code>FORMAT-TIME</code> - one of your slide times are not valid (<1 or >3600 seconds)
 
−
** '''IMPORTANT:''' The API does not enforce the minimum slide times for high-capacity devices. If your slides are too fast, you may encounter problems.
 
−
* <code>NOTFOUND</code> - the API key you used was not found
 
−
 
 
−
====Content Format====
 
−
The ''content'' for a set request must be of a very specific format. InfoCenter messages are composed like this:
 
−
 
 
−
<code>HELOWRLDWWWWWWWW|HOW R U?GGGGGGGG|GRAPHIC_Blank#$3|5|3</code>
 
−
 
 
−
This looks confusing, so let's take it step by step.
 
−
 
 
−
First, there are two sections separated by <code>#$</code>. The first section is the slide data, the second section is the slide times. Slides are individually separated by <code>|</code> characters. They must be padded to fit on the display they are set on. Each slide time is in whole seconds (integers, not floats), but slide data is more confusing:
 
−
 
 
−
<code>HOW R U?GGGGGGGG</code>
 
−
 
 
−
This is a single slide for a 8-character display. It is made up of the text and color strings concatenated together, each of which must be padded to <code>columns * rows</code> characters. So this could be an 8 x 1 display, or perhaps a 4 x 2 display. Think of these two strings as different "layers" of the slide - the color "layer" moves over to cover up the text "layer", coloring those characters individually.
 
−
 
 
−
All InfoCenter devices support the same colors, each with a single-digit color code - '''R'''ed, '''O'''range, '''A'''mber, '''Y'''ellow, '''G'''reen, '''B'''lue, '''P'''urple, and '''W'''hite. Any characters used for color other than these will be interpreted as white. So, if you wanted to make a rainbow-colored line, you could do this:
 
−
 
 
−
<code>^^^^^^^^ROAYGBPW</code> (remember, the ^ character turns into a full box character)
 
−
 
 
−
Remember that these strings are concatenated separately, not line-by-line. So, for an 8 x 3 display, it would look like this:
 
−
 
 
−
<code>^^^^^^^^^^^^^^^^^^^^^^^^ROAYGBPWROAYGBPWROAYGBPW</code>
 
−
 
 
−
====Alignment & Padding====
 
−
For multiple-line displays, you'll want to pad out each line individually, as the text will hard wrap. For example, on an 8 x 3 display (note that this uses <code>_</code> characters for spacing - because of wiki formatting, it's impossible to display multiple space characters, so just pretend):
 
−
 
 
−
<code>LEFT____ALIGNED_TEXT____WWWWWWWWWWWWWWWWWWWWWWWW</code>
 
−
 
 
−
<code>__I AM__CENTERED__TEXT__RRRRRRRRRRRRRRRRRRRRRRRR</code>
 
−
 
 
−
<code>___RIGHT_ALIGNED____TEXTAAAAAAAAAAAAAAAAAAAAAAAA</code>
 
−
 
 
−
Below is an LSL function for aligning each line:
 
−
 
 
−
<code>
 
−
string align(string in, string dir, integer length, string pad)
 
−
{
 
−
    if (pad=="") pad=" ";
 
−
    if (llToUpper(dir)=="L")
 
−
    {
 
−
        while (llStringLength(in) < length)
 
−
        {
 
−
            in=in+pad;
 
−
        }
 
−
    }
 
−
    else if (llToUpper(dir)=="R")
 
−
    {
 
−
        while (llStringLength(in) < length)
 
−
        {
 
−
            in=pad+in;
 
−
        }
 
−
    }
 
−
    else // assume center
 
−
    {
 
−
        integer osc=0; // we have to be a little smarter here
 
−
        while (llStringLength(in) < length)
 
−
        {
 
−
            if (osc) in=pad+in; // this will align left, then right,
 
−
            else in=in+pad;    // then left, then right...
 
−
            osc=!osc;          // ... effectively centering the text
 
−
        }
 
−
    }
 
−
    return llGetSubString(in,0,length-1); // cut off any excess if we added it on accident
 
−
}
 
−
</code>
 
−
 
 
−
This function allows you to align text left, right, or centered, to a specific length (in our case, <code>columns</code>), using an optional customizable padding string. You can use this padding string for colors.
 
−
 
 
−
For example, here's how to get the same text as above using this function (remember, we are on an 8 x 3 display):
 
−
 
 
−
<code>align("LEFT","L",8,"") + align("ALIGNED","L",8,"") + align("TEXT","L",8,"") + align("","",24,"W")</code> - we can leave the padding string empty and it will default to a space
 
−
 
 
−
<code>align("I AM","",8,"") + align("CENTERED","",8,"") + align("TEXT","",8,"") + align("","",24,"R")</code> - we can leave the alignment string empty and it will default to centered
 
−
 
 
−
<code>align("RIGHT","R",8,"") + align("ALIGNED","R",8,"") + align("TEXT","R",8,"") + align("","",24,"A")</code>
 
−
 
 
−
Note that we used a trick to create the color strings - by leaving the input and alignment strings empty, the function will simply create a string duplicating the padding string until it reaches the length. In our case, we used it to fill the entire display (8 x 3) with a single color. You could also make each line a separate color, or create a rainbow effect, like so:
 
−
 
 
−
<code>align("","",24,"^") + align("","",8,"R") + align("","",8,"G") + align("","",8,"B")</code> - would make a red, green, and blue line
 
−
 
 
−
<code>align("","",24,"^") + align("","",24,"ROAYGBPW")</code> - would make rainbow stripes (note that using any length of padding is fine, because any excess will be cut off)
 
−
 
 
−
Slides must be of the correct length for the device they are set on, or they will be rejected by the API. Remember, the formula is <code>columns * rows</code> for the text and color strings - so <code>columns * rows * 2</code> for both of them combined together.
 
−
 
 
−
====Example====
 
−
Okay, let's start backing up. Recall that all slides are separated by the <code>|</code> character, but there was one slide - GRAPHIC_Blank - which looks odd. That's because you can set graphic slides by simply taking the name of the graphic you want and adding <code>GRAPHIC_</code> to the beginning - for example, <code>GRAPHIC_Lane Open Down</code> for the Matrix. (If the graphic isn't supported by the model you are working with, it will show up as Blank.) Because graphics aren't colorable, you don't need to worry about color strings for them.
 
−
 
 
−
Once you have your desired slides and times, you can do something like this to "finalize" them into the required format:
 
−
 
 
−
<code>
 
−
string makeContent(list slide_data, list slide_times)
 
−
{
 
−
    return llDumpList2String(slide_data,"|") + "#$" + llDumpList2String(slide_times,"|");
 
−
}
 
−
</code>
 
−
 
 
−
Note that the slide_data and slide_times lists must be of equal length.
 
−
 
 
−
So, using the above functions (which are omitted for brevity), here's how to make (and send) a 3-slide centered message - obviously you'll have to replace ''apikey'' first. The entire script is included, and is extremely basic, but demonstrates how to also capture the response:
 
−
 
 
−
'''REMEMBER: The following example uses the 8x3 display from the InfoCenter Mobile. If you are going to use the API for any other size, you will need to modify the number of characters in each slide.'''
 
−
 
 
−
<code>
 
−
key api_request;
 
−
 
−
default
 
−
{
 
−
    state_entry()
 
−
    {
 
−
        api_request=llHTTPRequest("http://ntbigroup.com/gentek/infocenter/api.php?r=set&k=apikey",[HTTP_METHOD,"PUT"],
 
−
            makeContent([
 
−
                align("I AM","",8,"") + align("CENTERED","",8,"") + align("TEXT","",8,"") + align("","",24,"W") ,
 
−
                align("I AM","",8,"") + align("CENTERED","",8,"") + align("RED TEXT","",8,"") + align("","",24,"R") ,
 
−
                align("LOOK AT","",8,"") + align("THESE","",8,"") + align("COLORS","",8,"") + align("","",24,"ROAYGBPW")
 
−
            ],[3,3,5])
 
−
        );
 
−
    }
 
−
    http_response(key request_id, integer status, list metadata, string body)
 
−
    {
 
−
        if (request_id==api_request)
 
−
        {
 
−
            api_request=NULL_KEY;
 
−
            if (status==200) llOwnerSay("Response: "+body);
 
−
            else llOwnerSay("Server error. ("+(string)status+")");
 
−
        }
 
−
    }
 
−
}
 
−
</code>
 
−
 
 
−
===Setting a Device's Group===
 
−
You can set a device's group using the <code>grp</code> request:
 
−
 
 
−
<code>
 
−
llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=grp&k=apikey</nowiki>",[HTTP_METHOD,"PUT"],"New Group Name");
 
−
</code>
 
−
 
 
−
Replace ''apikey'' with the API key for the device you want to modify, and replace ''New Group Name'' with the group name that you want to add it to. To remove from a group, leave blank or enter ''NULL''.
 
−
 
 
−
This request can return the following in the <code>http_response</code> event:
 
−
 
 
−
* <code>OKNew Group Name</code> - the group was set successfully (the new group name is appended to <code>OK</code> - for example, when removing from a group, this will be <code>OKNULL</code>)
 
−
* <code>LENGTH</code> - your group name is too long (maximum 64 characters)
 
−
* <code>MISMATCH</code> - the group you want to join already exists and is for a different model
 
−
* <code>NOTFOUND</code> - the API key you used was not found
 
−
 
 
−
Remember, groups are never technically erased, so if adding to a group that previously existed but is currently empty, the group will be "recreated" using the old API key. This makes it possible to add devices to an empty group while knowing its API key in advance. However, it is not possible to get the group's API key through the API itself.
 
−
 
 
−
===Renaming a Device or Group===
 
−
You can rename a device or a group using the <code>ren</code> request:
 
−
 
 
−
<code>
 
−
llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=ren&k=apikey</nowiki>",[HTTP_METHOD,"PUT"],"New Name");
 
−
</code>
 
−
 
 
−
Replace ''apikey'' with the API key for the device or group you want to rename, and replace ''New Name'' with the new name you want to use. (This command will work for both devices and groups interchangeably.)
 
−
 
 
−
This request can return the following in the <code>http_response</code> event:
 
−
 
 
−
* <code>OKNew Name</code> - the name was set successfully (the new name is appended to <code>OK</code>)
 
−
* <code>LENGTH</code> - your name is too short or too long (1-64 characters required)
 
−
* <code>DUPLICATE</code> - the name you want to use already exists, or the device/group is already set to that name
 
−
* <code>NOTFOUND</code> - the API key you used was not found
 
−
 
 
−
Note that it is possible to remove all devices from a group by renaming the group to ''NULL''. However, this will make it impossible to use the group's API key again until a device is added to it.
 
−
 
 
−
===Querying Device/Group Information===
 
−
You can request information about a device or a group using the <code>inf</code> request:
 
−
 
 
−
<code>
 
−
llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=inf&k=apikey</nowiki>",[HTTP_METHOD,"PUT"],"");
 
−
</code>
 
−
 
 
−
Replace ''apikey'' with the API key for the device or group you want to get information about. The content field is not used. (This command will work for both devices and groups interchangeably.)
 
−
 
 
−
Running this command on its own without capturing the response is worthless, so you'll want to do that.
 
−
 
 
−
This request can return the following in the <code>http_response</code> event:
 
−
 
 
−
* For devices, a <code>#$</code>-separated string with the following: OK, DEVICE, device name/ID, device owner's username, device group, device model, device columns, device rows, max supported slides, location, UUID
 
−
** For example: <code>OK#$DEVICE#$Unnamed 1#$nelson.jenkins#$NULL#$InfoCenter Mobile#$8#$3#$42#$Prototype (142, 228, 43)#$9794a972-0131-3f33-7059-b04fc5ad92dd</code>
 
−
* For groups, a <code>#$</code>-separated string with the following: OK, GROUP, group name, group owner's username, device model, device columns, device rows, max supported slides, number of devices in group
 
−
** For example: <code>OK#$GROUP#$Test Group#$nelson.jenkins#$InfoCenter Personal#$16#$1#$60#$2</code>
 
−
* <code>NOTFOUND</code> - the API key you used was not found
 
−
 
 
−
You'll probably want to make use of [http://wiki.secondlife.com/wiki/LlParseStringKeepNulls llParseStringKeepNulls] for this - although it is not technically possible for null entries to appear, don't rule out the possibility. Also, do not expect this command to return data at this length forever - we may add additional fields (however unlikely) in the future, so don't check the response list length.
 
−
 
 
−
===Chat API===
 
−
Starting in v3.1, all InfoCenter displays support a basic chat API to set the display only. If you are experimenting with the API, it is strongly recommended that you start with the web-based API to ensure your requests are properly formatted, then switch to the chat API.
 
−
 
 
−
The chat API mode is different in the following ways:
 
−
 
 
−
* The chat API '''does not validate any data you send'''. The input sent to the chat API is processed immediately without regard for formatting mistakes. This can cause some odd behavior.
 
−
* The chat API can only accept 1024 characters per request, which can limit the data you can send per request. However, all InfoCenter displays can support at least one frame within 1024 characters.
 
−
* The chat API can only set the text on the display (a "set" request). It cannot set the display's group, rename it, or query it for information.
 
−
* Text sent to the display through the chat API will not update the saved text shown when accessing the display through the website editor.
 
−
* The chat API cannot set a display by its API key. To set a single display, you must use the display's UUID and use llRegionSayTo.
 
−
* The chat API can only set a single display at once using llRegionSayTo. It cannot send a message to an entire group. While you can set multiple displays through llWhisper, llSay, llShout, and llRegionSay, you cannot do so if you have different sizes of displays in range, as that will cause issues.
 
−
* The chat API will only work in the same region for displays owned by the same owner.
 
−
* The chat API is somewhat faster than the web API and can handle setting multiple devices at once or in sequence very quickly. Each display can also queue up to 64 requests and will process them in order.
 
−
 
 
−
The format for the chat API is the same as the web API's "set" request. However, the request is sent over channel -495310229, like so:
 
−
 
 
−
<code>
 
−
default
 
−
{
 
−
    state_entry()
 
−
    {
 
−
        llRegionSayTo("displayuuid", -495310229,
 
−
            makeContent([
 
−
                align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("TEXT", "", 8, "") + align("", "", 24, "W") ,
 
−
                align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("RED TEXT", "", 8, "") + align("", "", 24, "R") ,
 
−
                align("LOOK AT", "", 8, "") + align("THESE", "", 8, "") + align("COLORS", "", 8, "") + align("", "", 24, "ROAYGBPW")
 
−
            ], [3,3,5])
 
−
        );
 
−
    }
 
−
}
 
−
</code>
 
−
 
 
−
{{Gentek}}
 

Revision as of 22:50, 20 April 2021

The Global Mod Link System (GMLS) is a free, full-permission script system provided by the NTBI Group. Anyone can implement GMLS into their modifiable vehicle, and anyone can build mods that automatically position themselves when linked to a GMLS-compatible vehicle.

Overview

GMLS is a set of full-permissions scripts. It is intended for use in modifiable vehicles to simplify the installation of prebuilt modifications. For example, the NTBI Factory Lightbar Package uses GMLS to automatically position lightbars when linked to compatible vehicles.

Aftermarket modification manufacturers can set up GMLS by linking a copy of the modification to the desired vehicle and using the Calibration Tool to set up the Alignment Tool. Then, when an end-user links the modification to a compatible vehicle, the modification will reposition itself (and, if necessary, rescale itself) automatically. GMLS can also unlink certain prims from the vehicle for factory prim replacements.

GMLS comes with three scripts:

  • NTBI GMLS Alignment Tool - Inserted into aftermarket modifications and edited by the modification manufacturer to program alignment positions and other options.
  • NTBI GMLS Calibration Tool - Used to calibrate alignment positions; outputs alignment data to be placed in the Alignment Tool.
  • NTBI GMLS Vehicle Sample Script - Inserted into vehicles and edited by the vehicle manufacturer to define vehicle information for use by modifications.

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

Click here for the GMLS developer kit.

End-User Instructions

Refer to your vehicle's owner's guide for instructions on how to install GMLS-compatible equipment.

If the owner's guide does not provide instructions, the following is a general checklist for installing GMLS-compatible modifications:

  1. Ensure that the vehicle is turned off, including any lighting or other components that may change any attributes while installing the modification.
  2. Take a copy of your vehicle as-is. Modifications may cause damage or unlink prims accidentally. Save a copy now in case this happens!
  3. Rez the modification near your vehicle.
  4. Right click the modification and select "Edit".
  5. With the Edit window open, hold your SHIFT key and left click the vehicle. This should select both objects at once. Make sure you select the vehicle last.
  6. Press your CTRL + L keys, or click the "Link" button in the Edit window.
  7. If prompted, confirm that you want to link the two objects together.
  8. When linked, the modification should automatically position itself to the recommended position and resize if necessary.
  9. If prompted, grant link permissions. This may unlink some prims. Make sure to delete them after.
  10. If desired, you may usually move the equipment once linked.

If a modification does not use GMLS, is not compatible with your vehicle's GMLS system, or returns an error when linking using the above procedure, follow steps 1 through 6, then manually reposition the modification as needed.

Aftermarket Modification Manufacturer Instructions

Get the Alignment Tool and Calibration Tool from the GMLS developer kit.

Before continuing, make sure your mod is finished. Do not continue until you are sure you do not need to make any changes to your object.

  1. Make a two copies of your object. One will be used for calibration. The other will be distributed to your end-users.
  2. Place the "NTBI GMLS Alignment Tool" script in the distribution object (the one you will keep).
  3. Place the "NTBI GMLS Calibration Tool" script in the calibration object (the one you will link, then delete).

For each vehicle you want your object to be compatible with:

  1. Make a new copy of the calibration object. It should have the "NTBI GMLS Calibration Tool" script already in it.
  2. Rez the vehicle. Make sure it is the original size!
  3. Position the calibration object on the vehicle, exactly where you want it to be once installed by the end-user.
  4. Link the calibration object to the vehicle.
  5. Copy the script snippet line sent to local chat.
  6. Open the "NTBI GMLS Alignment Tool" script in the distribution object.
  7. Paste the script snippet line between the two marked lines at the top of the script. NOTE: The first part of each line is the GMLS ID of the vehicle you have calibrated to. If you see a line with the same GMLS ID, you have already calibrated to that vehicle, and only the first instance of that vehicle will be used.
  8. Save the "NTBI GMLS Alignment Tool" script.

Once finished, delete any calibration objects and vehicles.

If you want the root prim of the object to retain its physics type when linked to the vehicle, change root_no_physics to FALSE. (By default, the root prim of this object will be set to physics type "none" and the physics types of child prims will remain the same.)

If you want to have the GMLS script automatically unlink prims, list their names in the remove_prims list. If you do this, you can also change remove_move_dist to change the distance unlinked prims will move up, and you can change remove_recolor to FALSE if you do not want unlinked prims to be recolored bright red for visibility.

If you do not want the object to be set to temporary when unlinking prims in the remove_prims list so that they automatically delete themselves, change make_temp to FALSE.

When finished, make sure you test your modification on each compatible vehicle to make sure it works correctly.

API

The Alignment Tool and vehicle script send the following link messages that can be used to trigger additional scripts in your modification:

  • GMLS_REQUEST
    • Sent by Alignment Tool once linked. Vehicle responds with GMLS_ID if compatible. You can also send this manually once the GMLS script is finished if you need any information from GMLS_ID.
  • GMLS_ID
    • Key: [gmls_id]|[root scale]|[additional information]
    • Sent by vehicle in response to GMLS_REQUEST. Note that [root scale] is not the size of the root prim of the vehicle, but rather the ratio of the current size of the root to the original size of the root. For example, [root scale] on a vehicle that was upsized to twice its original size would be <2.0, 2.0, 2.0> regardless of its actual size.
  • GMLS_SUCCESS
    • Sent by Alignment Tool if the GMLS operation completed successfully and it is now safe to perform any configuration changes or whatever else on the newly linked-to vehicle.
  • GMLS_FAIL
    • Sent by Alignment Tool if the GMLS operation failed either because the object the modification was just linked to is not GMLS-compatible or the vehicle has a gmls_id that the modification was not calibrated for.
  • GMLS_CANCEL
    • Sent by Alignment Tool if the GMLS operation was cancelled by the user.

Vehicle Manufacturer Instructions

Get the Alignment Tool and Calibration Tool from the GMLS developer kit.

Before continuing, make sure your vehicle's root prim will not be resized before it is distributed. Do not continue until the root prim is finalized.

  1. Place the "NTBI GMLS Vehicle Sample Script" script in the vehicle. If you prefer, you can also integrate this script into another script in the vehicle to save memory.
  2. Edit the gmls_id string. You can use any string as long as it does not include the pipe ("|") character, but it should be limited to alphanumeric characters, underscores ("_"), and be up to 32 characters. The gmls_id must be unique for every vehicle that has a different layout of potential modification positions. For example, use different IDs for 2DR and 4DR variations of the same vehicle.
  3. Edit the gmls_default_root_size vector to be the size of the root prim of the vehicle. On most viewers, you can get this value by opening the Edit window, going to the Object tab, and pushing the "C" button next to Size. WARNING: This is not optional. Failure to set this value will cause GMLS modifications to align improperly.
  4. Save the "NTBI GMLS Vehicle Sample Script" script. If kept separate, you can limit the memory used by the script if you prefer.

Perform this procedure for each vehicle variation. Once finished, it is a good idea to test the GMLS settings by creating a simple object and following the Aftermarket Modification Manufacturer Instructions.

Changelog

Rev. 2

  • Added make_temp option.
  • Changed unlinking parts procedure so that unlinked prims are set to temporary if make_temp is enabled.

Rev. 1

  • Added GMLS_SUCCESS, GMLS_FAIL, and GMLS_CANCEL link messages.
  • Fixed erroring out and refusing to reposition if linked before permissions have been granted.
  • Fixed unlinking parts check running before checking if vehicle is compatible in the first place.
  • Fixed crosstalk when multiple GMLS modifications are rezzed at once.
  • Improved vehicle detection in slow regions by extending identification time from 2 seconds to 5 seconds.

Rev. 0

  • Initial public release.
Retrieved from "https://wiki.ntbigroup.com/index.php?title=InfoCenter&oldid=2957"