Difference between revisions of "InfoCenter v3 Legacy API"

 
(One intermediate revision by the same user not shown)
Line 2: Line 2:
  
 
==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.
 
 
 
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 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.
  
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.
+
Keep your API keys private! If anyone else gets a copy of your API key, they can control your device without you knowing. If this happens, you can reset your API key by clicking the ''Refresh'' link next to it - but you can't set your own API key, and any scripts that use the old key will no longer work.
  
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.
+
Unlike the InfoCenter API from v2, the v3 API is HTTP-based - 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. The object that sends the HTTP request can be anywhere in-world. If you prefer the chat-based API, scroll to the bottom of the page.
  
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.]
+
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.]
  
 
===Setting a Message===
 
===Setting a Message===
Line 36: Line 34:
 
  HELOWRLDWWWWWWWW|HOW R U?GGGGGGGG|GRAPHIC_Blank#$3|5|3
 
  HELOWRLDWWWWWWWW|HOW R U?GGGGGGGG|GRAPHIC_Blank#$3|5|3
  
This looks confusing, so let's take it step by step.
+
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). Each slide data is composed like so:
 
 
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:
 
  
 
  HOW R U?GGGGGGGG
 
  HOW R U?GGGGGGGG
  
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.
+
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.
  
 
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:
 
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:
Line 53: Line 49:
  
 
====Alignment & Padding====
 
====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):
+
For multiple-line displays, pad out each line individually, as the text will hard wrap. For example, on an 8 x 3 display:
  
  LEFT____ALIGNED_TEXT____WWWWWWWWWWWWWWWWWWWWWWWW
+
  LEFT    ALIGNED TEXT    WWWWWWWWWWWWWWWWWWWWWWWW
 
   
 
   
  __I AM__CENTERED__TEXT__RRRRRRRRRRRRRRRRRRRRRRRR
+
  I AM CENTERED  TEXT  RRRRRRRRRRRRRRRRRRRRRRRR
 
   
 
   
___RIGHT_ALIGNED____TEXTAAAAAAAAAAAAAAAAAAAAAAAA
+
    RIGHT ALIGNED    TEXTAAAAAAAAAAAAAAAAAAAAAAAA
  
 
Below is an LSL function for aligning each line:
 
Below is an LSL function for aligning each line:
Line 65: Line 61:
 
  string align(string in, string dir, integer length, string pad)
 
  string align(string in, string dir, integer length, string pad)
 
  {
 
  {
     if (pad=="") pad=" ";
+
     if (pad == "") pad = " ";
     if (llToUpper(dir)=="L")
+
     if (llToUpper(dir) == "L")
 
     {
 
     {
 
         while (llStringLength(in) < length)
 
         while (llStringLength(in) < length)
 
         {
 
         {
             in=in+pad;
+
             in = in + pad;
 
         }
 
         }
 
     }
 
     }
     else if (llToUpper(dir)=="R")
+
     else if (llToUpper(dir) == "R")
 
     {
 
     {
 
         while (llStringLength(in) < length)
 
         while (llStringLength(in) < length)
 
         {
 
         {
             in=pad+in;
+
             in = pad + in;
 
         }
 
         }
 
     }
 
     }
 
     else // assume center
 
     else // assume center
 
     {
 
     {
         integer osc=0; // we have to be a little smarter here
+
         integer osc = 0; // we have to be a little smarter here
 
         while (llStringLength(in) < length)
 
         while (llStringLength(in) < length)
 
         {
 
         {
             if (osc) in=pad+in; // this will align left, then right,
+
             if (osc) in = pad + in; // this will align left, then right,
             else in=in+pad;    // then left, then right...
+
             else in = in + pad;    // then left, then right...
             osc=!osc;           // ... effectively centering the text
+
             osc = !osc;             // ... effectively centering the text
 
         }
 
         }
 
     }
 
     }
     return llGetSubString(in,0,length-1); // cut off any excess if we added it on accident
+
     return llGetSubString(in, 0, length - 1); // cut off any excess if we added it on accident
 
  }
 
  }
  
Line 97: Line 93:
 
For example, here's how to get the same text as above using this function (remember, we are on an 8 x 3 display):
 
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("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("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>
+
<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:
+
Note the 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("", "", 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)
+
<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.
 
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.
 +
 +
====Graphic Slides====
 +
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.
  
 
====Example====
 
====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:
 
Once you have your desired slides and times, you can do something like this to "finalize" them into the required format:
  
 
  string makeContent(list slide_data, list slide_times)
 
  string makeContent(list slide_data, list slide_times)
 
  {
 
  {
     return llDumpList2String(slide_data,"|") + "#$" + llDumpList2String(slide_times,"|");
+
     return llDumpList2String(slide_data, "|") + "#$" + llDumpList2String(slide_times, "|");
 
  }
 
  }
  
 
Note that the slide_data and slide_times lists must be of equal length.
 
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:
+
So, using the above functions (which are omitted for brevity), here's how to make (and send) a 3-slide centered message - 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.'''
 
'''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.'''
Line 133: Line 130:
 
     state_entry()
 
     state_entry()
 
     {
 
     {
         api_request=llHTTPRequest("http://ntbigroup.com/gentek/infocenter/api.php?r=set&k=apikey",[HTTP_METHOD,"PUT"],
+
         api_request = llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=set&k=apikey</nowiki>", [HTTP_METHOD, "PUT"],
 
             makeContent([
 
             makeContent([
                 align("I AM","",8,"") + align("CENTERED","",8,"") + align("TEXT","",8,"") + align("","",24,"W") ,
+
                 align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("TEXT", "", 8, "") + align("", "", 8 * 3, "W") ,
                 align("I AM","",8,"") + align("CENTERED","",8,"") + align("RED TEXT","",8,"") + align("","",24,"R") ,
+
                 align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("RED TEXT", "", 8, "") + align("", "", 8 * 3, "R") ,
                 align("LOOK AT","",8,"") + align("THESE","",8,"") + align("COLORS","",8,"") + align("","",24,"ROAYGBPW")
+
                 align("LOOK AT", "", 8, "") + align("THESE", "", 8, "") + align("COLORS", "", 8, "") + align("", "", 8 * 3, "ROAYGBPW")
             ],[3,3,5])
+
             ], [3, 3, 5])
 
         );
 
         );
 
     }
 
     }
 
     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 + ")");
 
         }
 
         }
 
     }
 
     }
Line 155: Line 152:
 
You can set a device's group using the <code>grp</code> request:
 
You can set a device's group using the <code>grp</code> request:
  
  llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=grp&k=apikey</nowiki>",[HTTP_METHOD,"PUT"],"New Group Name");
+
  llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=grp&k=apikey</nowiki>", [HTTP_METHOD, "PUT"], "New Group Name");
  
 
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''.
 
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''.
Line 171: Line 168:
 
You can rename a device or a group using the <code>ren</code> request:
 
You can rename a device or a group using the <code>ren</code> request:
  
  llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=ren&k=apikey</nowiki>",[HTTP_METHOD,"PUT"],"New Name");
+
  llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=ren&k=apikey</nowiki>", [HTTP_METHOD, "PUT"], "New Name");
  
 
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.)
 
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.)
Line 187: Line 184:
 
You can request information about a device or a group using the <code>inf</code> request:
 
You can request information about a device or a group using the <code>inf</code> request:
  
  llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=inf&k=apikey</nowiki>",[HTTP_METHOD,"PUT"],"");
+
  llHTTPRequest("<nowiki>http://ntbigroup.com/gentek/infocenter/api.php?r=inf&k=apikey</nowiki>", [HTTP_METHOD, "PUT"], "");
  
 
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.)
 
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:
 
This request can return the following in the <code>http_response</code> event:
Line 201: Line 196:
 
* <code>NOTFOUND</code> - the API key you used was not found
 
* <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.
+
Use [http://wiki.secondlife.com/wiki/LlParseStringKeepNulls llParseStringKeepNulls] to split the response up. Also, do not rely on the return data to contain the same number of values forever; more may be added.
  
 
===Chat API===
 
===Chat API===
Line 225: Line 220:
 
         llRegionSayTo("displayuuid", -495310229,
 
         llRegionSayTo("displayuuid", -495310229,
 
             makeContent([
 
             makeContent([
                 align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("TEXT", "", 8, "") + align("", "", 24, "W") ,
+
                 align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("TEXT", "", 8, "") + align("", "", 8 * 3, "W") ,
                 align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("RED TEXT", "", 8, "") + align("", "", 24, "R") ,
+
                 align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("RED TEXT", "", 8, "") + align("", "", 8 * 3, "R") ,
                 align("LOOK AT", "", 8, "") + align("THESE", "", 8, "") + align("COLORS", "", 8, "") + align("", "", 24, "ROAYGBPW")
+
                 align("LOOK AT", "", 8, "") + align("THESE", "", 8, "") + align("COLORS", "", 8, "") + align("", "", 8 * 3, "ROAYGBPW")
             ], [3,3,5])
+
             ], [3, 3, 5])
 
         );
 
         );
 
     }
 
     }

Latest revision as of 16:42, 14 March 2020

The InfoCenter is a series of electronic text display signs (Personal, Notice, Highway, Matrix, and Mobile) sold by Gentek. This page covers the legacy API for the InfoCenter Series v3 and above. For the JSON API, which is highly recommended, see here.

API Documentation

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.

Keep your API keys private! If anyone else gets a copy of your API key, they can control your device without you knowing. If this happens, you can reset your API key by clicking the Refresh link next to it - but you can't set your own API key, and any scripts that use the old key will no longer work.

Unlike the InfoCenter API from v2, the v3 API is HTTP-based - 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. The object that sends the HTTP request can be anywhere in-world. If you prefer the chat-based API, scroll to the bottom of the page.

Invalid request types and internal errors will return ERROR. Although it is recommended to capture the request key and handle a response accordingly, it is not absolutely required. More information on LSL's http_response event is here.

Setting a Message

You can set a message using the set request:

llHTTPRequest("http://ntbigroup.com/gentek/infocenter/api.php?r=set&k=apikey",[HTTP_METHOD,"PUT"],"content");

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

This request can return the following in the http_response event:

  • OK - the message was sent to all devices succesfully
  • GROUPFAIL - the message was sent to some devices in the group, but some (not all) did not respond
  • FAIL - the message was not sent to any devices because none responded
  • FORMAT-SEPARATOR - your content string is not separated by #$
  • FORMAT-SLIDES - your slide data and slide time lists are not the same length, or you sent more slides than the selected device/group can handle
  • FORMAT-DATA - one of your slide data strings is not the correct length
  • FORMAT-TIME - 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.
  • NOTFOUND - 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:

HELOWRLDWWWWWWWW|HOW R U?GGGGGGGG|GRAPHIC_Blank#$3|5|3

There are two sections separated by #$. The first section is the slide data, the second section is the slide times. Slides are individually separated by | characters. They must be padded to fit on the display they are set on. Each slide time is in whole seconds (integers, not floats). Each slide data is composed like so:

HOW R U?GGGGGGGG

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 columns * rows characters. So this could be an 8 x 1 display, or perhaps a 4 x 2 display.

All InfoCenter devices support the same colors, each with a single-digit color code - Red, Orange, Amber, Yellow, Green, Blue, Purple, and White. 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:

^^^^^^^^ROAYGBPW

Remember that these strings are concatenated separately, not line-by-line. So, for an 8 x 3 display, it would look like this:

^^^^^^^^^^^^^^^^^^^^^^^^ROAYGBPWROAYGBPWROAYGBPW

Alignment & Padding

For multiple-line displays, pad out each line individually, as the text will hard wrap. For example, on an 8 x 3 display:

LEFT    ALIGNED TEXT    WWWWWWWWWWWWWWWWWWWWWWWW

  I AM  CENTERED  TEXT  RRRRRRRRRRRRRRRRRRRRRRRR

   RIGHT ALIGNED    TEXTAAAAAAAAAAAAAAAAAAAAAAAA

Below is an LSL function for aligning each line:

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
}

This function allows you to align text left, right, or centered, to a specific length (in our case, columns), 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):

align("LEFT", "L", 8, "") + align("ALIGNED", "L", 8, "") + align("TEXT", "L", 8, "") + align("", "", 24, "W") - we can leave the padding string empty and it will default to a space

align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("TEXT", "", 8, "") + align("", "", 24, "R") - we can leave the alignment string empty and it will default to centered

align("RIGHT", "R", 8, "") + align("ALIGNED", "R", 8, "") + align("TEXT", "R", 8, "") + align("", "", 24, "A")

Note the 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:

align("", "", 24, "^") + align("", "", 8, "R") + align("", "", 8, "G") + align("", "", 8, "B") - would make a red, green, and blue line

align("", "", 24, "^") + align("", "", 24, "ROAYGBPW") - 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 columns * rows for the text and color strings - so columns * rows * 2 for both of them combined together.

Graphic Slides

You can set graphic slides by simply taking the name of the graphic you want and adding GRAPHIC_ to the beginning - for example, GRAPHIC_Lane Open Down 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.

Example

Once you have your desired slides and times, you can do something like this to "finalize" them into the required format:

string makeContent(list slide_data, list slide_times)
{
    return llDumpList2String(slide_data, "|") + "#$" + llDumpList2String(slide_times, "|");
}

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

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("", "", 8 * 3, "W") ,
                align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("RED TEXT", "", 8, "") + align("", "", 8 * 3, "R") ,
                align("LOOK AT", "", 8, "") + align("THESE", "", 8, "") + align("COLORS", "", 8, "") + align("", "", 8 * 3, "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 + ")");
        }
    }
}

Setting a Device's Group

You can set a device's group using the grp request:

llHTTPRequest("http://ntbigroup.com/gentek/infocenter/api.php?r=grp&k=apikey", [HTTP_METHOD, "PUT"], "New Group Name");

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 http_response event:

  • OKNew Group Name - the group was set successfully (the new group name is appended to OK - for example, when removing from a group, this will be OKNULL)
  • LENGTH - your group name is too long (maximum 64 characters)
  • MISMATCH - the group you want to join already exists and is for a different model
  • NOTFOUND - 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 ren request:

llHTTPRequest("http://ntbigroup.com/gentek/infocenter/api.php?r=ren&k=apikey", [HTTP_METHOD, "PUT"], "New Name");

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 http_response event:

  • OKNew Name - the name was set successfully (the new name is appended to OK)
  • LENGTH - your name is too short or too long (1-64 characters required)
  • DUPLICATE - the name you want to use already exists, or the device/group is already set to that name
  • NOTFOUND - 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 inf request:

llHTTPRequest("http://ntbigroup.com/gentek/infocenter/api.php?r=inf&k=apikey", [HTTP_METHOD, "PUT"], "");

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

This request can return the following in the http_response event:

  • For devices, a #$-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: OK#$DEVICE#$Unnamed 1#$nelson.jenkins#$NULL#$InfoCenter Mobile#$8#$3#$42#$Prototype (142, 228, 43)#$9794a972-0131-3f33-7059-b04fc5ad92dd
  • For groups, a #$-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: OK#$GROUP#$Test Group#$nelson.jenkins#$InfoCenter Personal#$16#$1#$60#$2
  • NOTFOUND - the API key you used was not found

Use llParseStringKeepNulls to split the response up. Also, do not rely on the return data to contain the same number of values forever; more may be added.

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:

default
{
    state_entry()
    {
        llRegionSayTo("displayuuid", -495310229,
            makeContent([
                align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("TEXT", "", 8, "") + align("", "", 8 * 3, "W") ,
                align("I AM", "", 8, "") + align("CENTERED", "", 8, "") + align("RED TEXT", "", 8, "") + align("", "", 8 * 3, "R") ,
                align("LOOK AT", "", 8, "") + align("THESE", "", 8, "") + align("COLORS", "", 8, "") + align("", "", 8 * 3, "ROAYGBPW")
            ], [3, 3, 5])
        );
    }
}