Difference between revisions of "InfoCenter"

imported>NelsonJenkins
m
 
(12 intermediate revisions by 2 users not shown)
Line 7: Line 7:
 
| company          = [[Gentek]]
 
| company          = [[Gentek]]
 
| available        = Marketplace & In-World
 
| available        = Marketplace & In-World
−
| url              = '''Coming Soon'''
+
| 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]'''
 
}}
 
}}
  
Line 73: Line 73:
 
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.
 
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.
+
If your device disappears in-world, it will remain in the InfoCenter Manager. 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.
−
 
 
−
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.
 
  
 
==Updates & Release Notes==
 
==Updates & Release Notes==
 
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).
 
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).
 +
* '''v3.2'''
 +
** Added JSON API (backwards-compatible with earlier versions).
 +
** Improved font.
 +
** Fixed bug where graphic frame would be displayed at the same time as rendering text.
 +
* '''v3.1'''
 +
** Added chat API.
 
* '''v3.0'''
 
* '''v3.0'''
 
** Upgraded public release.
 
** Upgraded public release.
Line 84: Line 88:
  
 
==API Documentation==
 
==API Documentation==
−
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.
+
For the legacy API, including the chat API, [[InfoCenter v3 Legacy API|see here]].
  
−
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.
+
The InfoCenter signs are controllable using an HTTP/JSON API. This can be used from LSL or from any software or server capable of forming JSON strings and sending HTTP requests.
  
−
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.
+
The API endpoint is http://ntbigroup.com/gentek/infocenter/api_json.php.
  
−
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).
+
A sample JSON request is as follows:
  
−
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.]
+
{
 +
"request": "set_text",
 +
"api_key": "1234567890123456",
 +
"frames": [
 +
{
 +
"text": "Hello World!",
 +
"color": "",
 +
"align": "center",
 +
"word_wrap": true,
 +
"ignore_length": true,
 +
"time": 3
 +
},
 +
{
 +
"lines": [
 +
{
 +
"text": "ABCDEFGHIJKLMNOP",
 +
"color": "ROAYGBPWROAYGBPW",
 +
"align": "left"
 +
},
 +
{
 +
"text": "^^^^^^^^^^^^^^^^",
 +
"align": "right"
 +
}
 +
],
 +
"ignore_length": true,
 +
"time": 3
 +
},
 +
{
 +
"graphic": "Stop",
 +
"time": 3
 +
}
 +
]
 +
}
  
−
===Setting a Message===
+
===Required Key/Values===
−
You can set a message using the <code>set</code> request:
+
The JSON request must be an object with the following key-value pairs:
  
−
<code>
+
* '''request''': Must be one of the following request types:
−
llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=set&k=apikey</nowiki>",[HTTP_METHOD,"PUT"],"content");
+
** '''"set_text"''': Sets the text shown on a display or group of displays.
−
</code>
+
** '''"set_name"''': Sets the name of a display or group.
 +
** '''"set_group"''': Adds or removes a display to/from a group.
 +
** '''"get_info"''': Gets information about a display or group.
  
−
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.)
+
For '''set_text''' requests, the following key-value pairs are also required:
 +
* '''api_key''': The API key of the display or group to set. Remember to keep your API key private, because there is no other authentication.
 +
* '''frames''': An array of objects, each object being a single frame. See below for details on how these objects are defined.
 +
** Multiple frames can be sent in the same request, and they will cycle. The maximum number of frames is defined by the type of display being used. If the number of frames in the request exceeds the maximum, the server will return an error.
  
−
This request can return the following in the <code>http_response</code> event:
+
For '''set_name''' requests, the following key-value pairs are also required:
 +
* '''api_key''': The API key of the display or group to rename.
 +
* '''name''': The new name to use. Must be between 1 and 64 characters.
  
−
* <code>OK</code> - the message was sent to all devices succesfully
+
For '''set_group''' requests, the following key-value pairs are also required:
−
* <code>GROUPFAIL</code> - the message was sent to some devices in the group, but some (not all) did not respond
+
* '''api_key''': The API key of the display to add to or remove from the group. Remember that the display and the group (if it exists) must be owned by the same user; displays cannot be added to groups owned by other users.
−
* <code>FAIL</code> - the message was not sent to any devices because none responded
+
* Only one of the following key-value pairs:
−
* <code>FORMAT-SEPARATOR</code> - your content string is not separated by <code>#$</code>
+
** '''group_api_key''': The API key of the group to add the display to.
−
* <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
+
** '''group_name''': The name of the group to add the display to. Must be between 1 and 64 characters.
−
* <code>FORMAT-DATA</code> - one of your slide data strings is not the correct length
+
** '''group_remove''': Must be true to enable (JSON_TRUE in LSL). If enabled, will remove the display from its group.
−
* <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====
+
For '''get_info''' requests, the following key-value pair is also required:
−
The ''content'' for a set request must be of a very specific format. InfoCenter messages are composed like this:
+
* '''api_key''': The API key of the display or group to get info about.
  
−
<code>HELOWRLDWWWWWWWW|HOW R U?GGGGGGGG|GRAPHIC_Blank#$3|5|3</code>
+
===set_text Frame Object===
 +
Each frame must have only one of these required key-value pairs:
  
−
This looks confusing, so let's take it step by step.
+
* '''text''': A string of text to display.
 +
* '''lines''': An array of objects, each object being a single line on the display. Allows more precision in where text is displayed.
 +
* '''graphic''': The name of a graphic supported by this display (see below).
  
−
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:
+
The key-value above used determines which type of frame it is, which determines which options are available.
  
−
<code>HOW R U?GGGGGGGG</code>
+
====set_text Text Frame Type====
 +
A '''text''' frame type can have the following options:
  
−
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.
+
* '''text''': Required. A string of text to display.
 +
* '''color''': Optional. A color string (see below). If an empty string or not defined, "A" is used.
 +
** If the color string is shorter than the text string, the rest of the text uses the last color character.
 +
** If '''word_wrap''' is enabled, the entire frame will only be the color of the last color character due to technical limitations.
 +
* '''align''': Optional. Either "left", "center", or "right". Can also be "l", "c", or "r". If not defined, aligned to left.
 +
** If '''word_wrap''' is enabled, this will align each line. If it is disabled, this will only align the last line, because the lines before it (if any) will be the full width of the display.
 +
* '''word_wrap''': Optional. Must be true to enable (JSON_TRUE in LSL). If enabled, words are wrapped naturally. If disabled or not defined, text is "hard" wrapped to the full width of the display. It is a good idea to enable '''ignore_length''' to avoid errors if words wrap beyond the limits of the display.
 +
* '''ignore_length''': Optional. Must be true to enable (JSON_TRUE in LSL). If enabled, the server will not check the length of the text. If disabled or not defined, the server will return an error if the text exceeds the maximum the display can show.
 +
* '''time''': Optional. A length of time in seconds, between 1 and 3600, to display the frame. If not defined, the time will default to 5 seconds.
 +
** The server does not check the minimum time it would take to render the display, so very short frame times may produce unintended results.
  
−
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:
+
====set_text Lines Frame Type====
 +
A '''lines''' frame type can have the following options:
  
−
<code>^^^^^^^^ROAYGBPW</code> (remember, the ^ character turns into a full box character)
+
* '''lines''': Required. An array of objects, each object being a single line on the display. Allows more precision in where text is displayed. Each line can have the following options:
 +
** '''text''': Required. A string of text to display on the line.
 +
** '''color''': Optional. Optional. A color string (see below). If the color string is shorter than the text string, the rest of the text uses the last color character. If the '''color''' option is not defined or is empty, "A" is used. If an invalid character is used, it is replaced with "W".
 +
** '''align''': Optional. Either "left", "center", or "right". Can also be "l", "c", or "r". If not defined, aligned to left.
 +
* '''ignore_length''': Optional. Must be true to enable (JSON_TRUE in LSL). If enabled, the server will not check the length of the text on each line, nor will it check the number of lines included in the request. If disabled or not defined, the server will return an error if the text exceeds the maximum the display can show in either dimension.
 +
* '''time''': Optional. A length of time in seconds, between 1 and 3600, to display the frame. If not defined, the time will default to 5 seconds.
 +
** The server does not check the minimum time it would take to render the display, so very short frame times may produce unintended results.
  
−
Remember that these strings are concatenated separately, not line-by-line. So, for an 8 x 3 display, it would look like this:
+
====set_text Graphic Frame Type====
 +
A '''graphic''' frame type can have the following options:
  
−
<code>^^^^^^^^^^^^^^^^^^^^^^^^ROAYGBPWROAYGBPWROAYGBPW</code>
+
* '''graphic''': The name of a graphic supported by this display. This is case-insensitive, but must otherwise be an exact match to a supported graphic, or the server will return an error. The supported graphics are as follows:
 +
** ''InfoCenter Highway'': "Stop", "Hazard", "Do Not Enter"
 +
** ''InfoCenter Matrix'': "Stop", "Hazard", "Do Not Enter", "Detour Left", "Detour Right", "Lane Open Down", "Lane Open Up", "Lane Closed", "Lane Left Down", "Lane Right Down", "Lane Left Up", "Lane Right Up", "One Way Left", "One Way Right", "Yield", "Do Not Pass", "Stay In Lane", "No Trucks", "Trucks OK", "Speed Limit 5", "Speed Limit 10", "Speed Limit 15", "Speed Limit 20", "Speed Limit 25", "Speed Limit 30", "Speed Limit 35", "Speed Limit 40", "Speed Limit 45", "Speed Limit 50", "Speed Limit 55", "Speed Limit 60", "Speed Limit 65", "Speed Limit 70", "Speed Limit 75", "Speed Limit 80", "Keep Right", "Keep Left", "No Right Turn", "No Left/U Turn", "No Left Turn", "No U Turn", "Straight Or Left", "Straight Or Right", "Straight Only", "Left Turn Only", "Right Turn Only", "No Turns"
 +
** ''InfoCenter Notice'': "Information", "Today's Events", "Huge Sale", "Discounts", "Best Deals", "Notice", "Warning", "Danger"
 +
** ''InfoCenter Personal'': "Sale", "Come On In", "News Flash", "Happy 4th", "Welcome", "Open", "Closed", "Thank You", "No Smoking"
 +
** ''InfoCenter Mobile'': "Stop", "Hazard", "Do Not Enter", "Chase Right", "Chase Left", "Arrow Right", "Arrow Left", "Flash Right", "Flash Left", "Chevron Right", "Chevron Left", "Arrow Split", "Flash Split", "Flagger", "Stop Left", "Stop Right", "Detour Left", "Detour Right"
 +
* '''time''': Optional. A length of time in seconds, between 1 and 3600, to display the frame. If not defined, the time will default to 5 seconds.
  
−
====Alignment & Padding====
+
===HTTP Request Format===
−
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):
+
The required URL, as part of an LSL HTTP request, is as follows:
  
−
<code>LEFT____ALIGNED_TEXT____WWWWWWWWWWWWWWWWWWWWWWWW</code>
+
llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api_json.php</nowiki>", [HTTP_METHOD, "PUT"], json_request);
  
−
<code>__I AM__CENTERED__TEXT__RRRRRRRRRRRRRRRRRRRRRRRR</code>
+
This URL is also accessible from any web server.
  
−
<code>___RIGHT_ALIGNED____TEXTAAAAAAAAAAAAAAAAAAAAAAAA</code>
+
===HTTP Response Format===
 +
The server returns a JSON object with the following key-value pairs:
  
−
Below is an LSL function for aligning each line:
+
* '''api''': Always "infocenter_json".
 +
* '''status''': Either "ok" or "error".
 +
* '''error''': An error number. Only included if '''status''' is "error". Include this number if possible when contacting support.
 +
* '''text''': A textual status response. If successful, will include how many displays/groups succeeded and failed. If failed, will include a human-readable error message.
  
−
<code>
+
For '''get_info''' requests, the following key-value pairs are also returned:
−
string align(string in, string dir, integer length, string pad)
+
* '''api_key_type''': Either "display" or "group".
−
{
+
* '''name''': The name of the display or group.
−
    if (pad=="") pad=" ";
+
* '''owner''': The owner of the display or group.
−
    if (llToUpper(dir)=="L")
+
* '''uuid''': The UUID of the display. Only included if '''api_key_type''' is '''"display"'''.
−
    {
+
* '''location''': The location of the display in the format <code>Region Name (128, 128, 20)</code>. May not be accurate if the display has been moved since it was rezzed. Only included if '''api_key_type''' is '''"display"'''.
−
        while (llStringLength(in) < length)
+
* '''group''': The group that the display is in. If the display is not in a group, an empty string is returned. Only included if '''api_key_type''' is '''"display"'''.
−
        {
+
* '''type''': The display type, such as "InfoCenter Mobile", for the display or group.
−
            in=in+pad;
+
* '''cols''': The number of columns in each row of the display or group type.
−
        }
+
* '''rows''': The number of rows of characters that the display or group type can show.
−
    }
+
* '''frames''': The maximum number of frames that the display or group type can show.
−
    else if (llToUpper(dir)=="R")
+
* '''displays''': An array of API keys of displays in the group. Only included if '''api_key_type''' is '''"group"'''.
−
    {
 
−
        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:
+
===LSL Sample===
 +
A sample LSL script, implementing the JSON sample above, is below:
  
−
<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:
 
−
 
−
<code>
 
 
  key api_request;
 
  key api_request;
−
 
 
  default
 
  default
 
  {
 
  {
 
     state_entry()
 
     state_entry()
 
     {
 
     {
−
         api_request=llHTTPRequest("http://ntbigroup.com/gentek/infocenter/api.php?r=set&k=apikey",[HTTP_METHOD,"PUT"],
+
         string json_request = llList2Json(JSON_OBJECT, [
−
             makeContent([
+
            "request", "\"set_text\"",
−
                 align("I AM","",8,"") + align("CENTERED","",8,"") + align("TEXT","",8,"") + align("","",24,"W") ,
+
            "api_key", "\"1234567890123456\"",
−
                 align("I AM","",8,"") + align("CENTERED","",8,"") + align("RED TEXT","",8,"") + align("","",24,"R") ,
+
             "frames", llList2Json(JSON_ARRAY, [
−
                align("LOOK AT","",8,"") + align("THESE","",8,"") + align("COLORS","",8,"") + align("","",24,"ROAYGBPW")
+
                 llList2Json(JSON_OBJECT, [
−
             ],[3,3,5])
+
                    "text", "\"Hello World!\"",
−
        );
+
                    "color", "",
 +
                    "align", "center",
 +
                    "word_wrap", JSON_TRUE,
 +
                    "ignore_length", JSON_TRUE,
 +
                    "time", 3
 +
                    ]),
 +
                 llList2Json(JSON_OBJECT, [
 +
                    "lines", llList2Json(JSON_ARRAY, [
 +
                        llList2Json(JSON_OBJECT, [
 +
                            "text", "\"ABCDEFGHIJKLMNOP\"",
 +
                            "color", "\"ROAYGBPWROAYGBPW\"",
 +
                            "align", "left"
 +
                            ]),
 +
                        llList2Json(JSON_OBJECT, [
 +
                            "text", "\"^^^^^^^^^^^^^^^^\"",
 +
                            "align", "r"
 +
                            ])
 +
                        ]),
 +
                    "ignore_length", JSON_TRUE,
 +
                    "time", 5
 +
                    ]),
 +
                llList2Json(JSON_OBJECT, [
 +
                    "graphic", "\"Stop\"",
 +
                    "time", 3
 +
                    ])
 +
                ])
 +
             ]);
 +
        api_request = llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api_json.php</nowiki>", [HTTP_METHOD, "PUT"], json_request);
 
     }
 
     }
 
     http_response(key request_id, integer status, list metadata, string body)
 
     http_response(key request_id, integer status, list metadata, string body)
 
     {
 
     {
−
         if (request_id==api_request)
+
         if (request_id == api_request)
 
         {
 
         {
−
             api_request=NULL_KEY;
+
             api_request = NULL_KEY;
−
             if (status==200) llOwnerSay("Response: "+body);
+
             if (status == 200) llOwnerSay("Response: " + body);
−
             else llOwnerSay("Server error. ("+(string)status+")");
+
             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:
+
Note that LSL's JSON handling requires you to wrap values in escaped quotes, like so:
  
−
* 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
+
["request", "\"set_text\""]
−
** 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.
+
You do not need to wrap keys in escaped quotes because the specification does not include any keys that could be interpreted as raw JSON.
  
 
{{Gentek}}
 
{{Gentek}}

Latest revision as of 14:23, 15 January 2021

InfoCenter
200px

InfoCenter Display Kit vendor image.
Creator Nelson Jenkins, SLI Komarov
Launch year 2008, upgraded in 2014
Company Gentek
Availability Marketplace & In-World
InfoCenter Display Kit
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.

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: Mobile, Highway, or Personal

Models

The InfoCenter is made up of two separate products - the InfoCenter Display Kit, and the InfoCenter Mobile.

InfoCenter Display Kit

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):

  • 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.
  • 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 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.

Setup & Use

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.

All InfoCenter devices are accessible through the 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 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.

Setting a Message

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.

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.

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.

  • 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.
    • 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.

Using Templates

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.
  • 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

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.
  • 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 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. 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.

Updates & Release Notes

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).

  • v3.2
    • Added JSON API (backwards-compatible with earlier versions).
    • Improved font.
    • Fixed bug where graphic frame would be displayed at the same time as rendering text.
  • v3.1
    • Added chat API.
  • v3.0
    • Upgraded public release.
    • Rewrote everything, so old release notes are irrelevant.

API Documentation

For the legacy API, including the chat API, see here.

The InfoCenter signs are controllable using an HTTP/JSON API. This can be used from LSL or from any software or server capable of forming JSON strings and sending HTTP requests.

The API endpoint is http://ntbigroup.com/gentek/infocenter/api_json.php.

A sample JSON request is as follows: 

{
	"request": "set_text",
	"api_key": "1234567890123456",
	"frames": [
		{
			"text": "Hello World!",
			"color": "",
			"align": "center",
			"word_wrap": true,
			"ignore_length": true,
			"time": 3
		},
		{
			"lines": [
				{
					"text": "ABCDEFGHIJKLMNOP",
					"color": "ROAYGBPWROAYGBPW",
					"align": "left"
				},
				{
					"text": "^^^^^^^^^^^^^^^^",
					"align": "right"
				}
			],
			"ignore_length": true,
			"time": 3
		},
		{
			"graphic": "Stop",
			"time": 3
		}
	]
}

Required Key/Values

The JSON request must be an object with the following key-value pairs:

  • request: Must be one of the following request types:
    • "set_text": Sets the text shown on a display or group of displays.
    • "set_name": Sets the name of a display or group.
    • "set_group": Adds or removes a display to/from a group.
    • "get_info": Gets information about a display or group.

For set_text requests, the following key-value pairs are also required:

  • api_key: The API key of the display or group to set. Remember to keep your API key private, because there is no other authentication.
  • frames: An array of objects, each object being a single frame. See below for details on how these objects are defined.
    • Multiple frames can be sent in the same request, and they will cycle. The maximum number of frames is defined by the type of display being used. If the number of frames in the request exceeds the maximum, the server will return an error.

For set_name requests, the following key-value pairs are also required:

  • api_key: The API key of the display or group to rename.
  • name: The new name to use. Must be between 1 and 64 characters.

For set_group requests, the following key-value pairs are also required:

  • api_key: The API key of the display to add to or remove from the group. Remember that the display and the group (if it exists) must be owned by the same user; displays cannot be added to groups owned by other users.
  • Only one of the following key-value pairs:
    • group_api_key: The API key of the group to add the display to.
    • group_name: The name of the group to add the display to. Must be between 1 and 64 characters.
    • group_remove: Must be true to enable (JSON_TRUE in LSL). If enabled, will remove the display from its group.

For get_info requests, the following key-value pair is also required:

  • api_key: The API key of the display or group to get info about.

set_text Frame Object

Each frame must have only one of these required key-value pairs:

  • text: A string of text to display.
  • lines: An array of objects, each object being a single line on the display. Allows more precision in where text is displayed.
  • graphic: The name of a graphic supported by this display (see below).

The key-value above used determines which type of frame it is, which determines which options are available.

set_text Text Frame Type

A text frame type can have the following options:

  • text: Required. A string of text to display.
  • color: Optional. A color string (see below). If an empty string or not defined, "A" is used.
    • If the color string is shorter than the text string, the rest of the text uses the last color character.
    • If word_wrap is enabled, the entire frame will only be the color of the last color character due to technical limitations.
  • align: Optional. Either "left", "center", or "right". Can also be "l", "c", or "r". If not defined, aligned to left.
    • If word_wrap is enabled, this will align each line. If it is disabled, this will only align the last line, because the lines before it (if any) will be the full width of the display.
  • word_wrap: Optional. Must be true to enable (JSON_TRUE in LSL). If enabled, words are wrapped naturally. If disabled or not defined, text is "hard" wrapped to the full width of the display. It is a good idea to enable ignore_length to avoid errors if words wrap beyond the limits of the display.
  • ignore_length: Optional. Must be true to enable (JSON_TRUE in LSL). If enabled, the server will not check the length of the text. If disabled or not defined, the server will return an error if the text exceeds the maximum the display can show.
  • time: Optional. A length of time in seconds, between 1 and 3600, to display the frame. If not defined, the time will default to 5 seconds.
    • The server does not check the minimum time it would take to render the display, so very short frame times may produce unintended results.

set_text Lines Frame Type

A lines frame type can have the following options:

  • lines: Required. An array of objects, each object being a single line on the display. Allows more precision in where text is displayed. Each line can have the following options:
    • text: Required. A string of text to display on the line.
    • color: Optional. Optional. A color string (see below). If the color string is shorter than the text string, the rest of the text uses the last color character. If the color option is not defined or is empty, "A" is used. If an invalid character is used, it is replaced with "W".
    • align: Optional. Either "left", "center", or "right". Can also be "l", "c", or "r". If not defined, aligned to left.
  • ignore_length: Optional. Must be true to enable (JSON_TRUE in LSL). If enabled, the server will not check the length of the text on each line, nor will it check the number of lines included in the request. If disabled or not defined, the server will return an error if the text exceeds the maximum the display can show in either dimension.
  • time: Optional. A length of time in seconds, between 1 and 3600, to display the frame. If not defined, the time will default to 5 seconds.
    • The server does not check the minimum time it would take to render the display, so very short frame times may produce unintended results.

set_text Graphic Frame Type

A graphic frame type can have the following options:

  • graphic: The name of a graphic supported by this display. This is case-insensitive, but must otherwise be an exact match to a supported graphic, or the server will return an error. The supported graphics are as follows:
    • InfoCenter Highway: "Stop", "Hazard", "Do Not Enter"
    • InfoCenter Matrix: "Stop", "Hazard", "Do Not Enter", "Detour Left", "Detour Right", "Lane Open Down", "Lane Open Up", "Lane Closed", "Lane Left Down", "Lane Right Down", "Lane Left Up", "Lane Right Up", "One Way Left", "One Way Right", "Yield", "Do Not Pass", "Stay In Lane", "No Trucks", "Trucks OK", "Speed Limit 5", "Speed Limit 10", "Speed Limit 15", "Speed Limit 20", "Speed Limit 25", "Speed Limit 30", "Speed Limit 35", "Speed Limit 40", "Speed Limit 45", "Speed Limit 50", "Speed Limit 55", "Speed Limit 60", "Speed Limit 65", "Speed Limit 70", "Speed Limit 75", "Speed Limit 80", "Keep Right", "Keep Left", "No Right Turn", "No Left/U Turn", "No Left Turn", "No U Turn", "Straight Or Left", "Straight Or Right", "Straight Only", "Left Turn Only", "Right Turn Only", "No Turns"
    • InfoCenter Notice: "Information", "Today's Events", "Huge Sale", "Discounts", "Best Deals", "Notice", "Warning", "Danger"
    • InfoCenter Personal: "Sale", "Come On In", "News Flash", "Happy 4th", "Welcome", "Open", "Closed", "Thank You", "No Smoking"
    • InfoCenter Mobile: "Stop", "Hazard", "Do Not Enter", "Chase Right", "Chase Left", "Arrow Right", "Arrow Left", "Flash Right", "Flash Left", "Chevron Right", "Chevron Left", "Arrow Split", "Flash Split", "Flagger", "Stop Left", "Stop Right", "Detour Left", "Detour Right"
  • time: Optional. A length of time in seconds, between 1 and 3600, to display the frame. If not defined, the time will default to 5 seconds.

HTTP Request Format

The required URL, as part of an LSL HTTP request, is as follows: 

llHTTPRequest("http://ntbigroup.com/gentek/infocenter/api_json.php", [HTTP_METHOD, "PUT"], json_request);

This URL is also accessible from any web server.

HTTP Response Format

The server returns a JSON object with the following key-value pairs:

  • api: Always "infocenter_json".
  • status: Either "ok" or "error".
  • error: An error number. Only included if status is "error". Include this number if possible when contacting support.
  • text: A textual status response. If successful, will include how many displays/groups succeeded and failed. If failed, will include a human-readable error message.

For get_info requests, the following key-value pairs are also returned:

  • api_key_type: Either "display" or "group".
  • name: The name of the display or group.
  • owner: The owner of the display or group.
  • uuid: The UUID of the display. Only included if api_key_type is "display".
  • location: The location of the display in the format Region Name (128, 128, 20). May not be accurate if the display has been moved since it was rezzed. Only included if api_key_type is "display".
  • group: The group that the display is in. If the display is not in a group, an empty string is returned. Only included if api_key_type is "display".
  • type: The display type, such as "InfoCenter Mobile", for the display or group.
  • cols: The number of columns in each row of the display or group type.
  • rows: The number of rows of characters that the display or group type can show.
  • frames: The maximum number of frames that the display or group type can show.
  • displays: An array of API keys of displays in the group. Only included if api_key_type is "group".

LSL Sample

A sample LSL script, implementing the JSON sample above, is below: 

key api_request;
default
{
    state_entry()
    {
        string json_request = llList2Json(JSON_OBJECT, [
            "request", "\"set_text\"",
            "api_key", "\"1234567890123456\"",
            "frames", llList2Json(JSON_ARRAY, [
                llList2Json(JSON_OBJECT, [
                    "text", "\"Hello World!\"",
                    "color", "",
                    "align", "center",
                    "word_wrap", JSON_TRUE,
                    "ignore_length", JSON_TRUE,
                    "time", 3
                    ]),
                llList2Json(JSON_OBJECT, [
                    "lines", llList2Json(JSON_ARRAY, [
                        llList2Json(JSON_OBJECT, [
                            "text", "\"ABCDEFGHIJKLMNOP\"",
                            "color", "\"ROAYGBPWROAYGBPW\"",
                            "align", "left"
                            ]),
                        llList2Json(JSON_OBJECT, [
                            "text", "\"^^^^^^^^^^^^^^^^\"",
                            "align", "r"
                            ])
                        ]),
                    "ignore_length", JSON_TRUE,
                    "time", 5
                    ]),
                llList2Json(JSON_OBJECT, [
                    "graphic", "\"Stop\"",
                    "time", 3
                    ])
                ])
            ]);
        api_request = llHTTPRequest("http://ntbigroup.com/gentek/infocenter/api_json.php", [HTTP_METHOD, "PUT"], json_request);
    }
    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 + ")");
        }
    }
}

Note that LSL's JSON handling requires you to wrap values in escaped quotes, like so: 

["request", "\"set_text\""]

You do not need to wrap keys in escaped quotes because the specification does not include any keys that could be interpreted as raw JSON.


Retrieved from "https://wiki.ntbigroup.com/index.php?title=InfoCenter&oldid=2930"