BrightSign Object FW 5.1 User Manual

OBJECT REFERENCE MANUAL

Firmware Versions 5.1.x

BrightSign, LLC. 16780 Lark Ave., Suite B Los Gatos, CA 95032 | 408-852-9263 | www.brightsign.biz

TABLE OF CONTENTS

INTRODUCTION .................................................................................................................... 1

INTERFACES AND METHODS OVERVIEW ........................................................................ 2

Classes .............................................................................................................................................................................. 3

Object and Class Name Syntax ......................................................................................................................................... 3

Zones................................................................................................................................................................................. 3

Event Loops ....................................................................................................................................................................... 4

BrightSign Object Library ................................................................................................................................................... 5

BRIGHTSCRIPT CORE OBJECTS ....................................................................................... 6

roArray ............................................................................................................................................................................... 6

roAssociativeArray ............................................................................................................................................................. 8

roBoolean ........................................................................................................................................................................ 10

roByteArray ...................................................................................................................................................................... 11

roDouble, roIntrinsicDouble ............................................................................................................................................. 13

roFunction ........................................................................................................................................................................ 14

roGlobal ........................................................................................................................................................................... 15

roInt, roFloat, roString ...................................................................................................................................................... 23

roList ................................................................................................................................................................................ 27

roRegex ........................................................................................................................................................................... 30

roXMLElement ................................................................................................................................................................. 32

roXMLList ........................................................................................................................................................................ 36

PRESENTATION AND WIDGET OBJECTS ....................................................................... 39

roAudioEventMx .............................................................................................................................................................. 39

roAudioOutput ................................................................................................................................................................. 40

roAudioPlayer .................................................................................................................................................................. 42

roAudioPlayerMx ............................................................................................................................................................. 49

roCanvasWidget .............................................................................................................................................................. 54

roClockWidget ................................................................................................................................................................. 60

roHtmlWidget ................................................................................................................................................................... 63

roImageBuffer .................................................................................................................................................................. 68

roImagePlayer ................................................................................................................................................................. 69

roImageWidget ................................................................................................................................................................ 74

roRectangle ..................................................................................................................................................................... 77

roShoutcastStream .......................................................................................................................................................... 78

roShoutcastStreamEvent ................................................................................................................................................. 79

roTextField ....................................................................................................................................................................... 80

roTextWidget ................................................................................................................................................................... 83

roVideoEvent, roAudioEvent ............................................................................................................................................ 88

roVideoInput .................................................................................................................................................................... 90

roVideoMode ................................................................................................................................................................... 93

roVideoPlayer .................................................................................................................................................................. 99

roTouchCalibrationEvent ............................................................................................................................................... 114

roTouchEvent ................................................................................................................................................................ 115

roTouchScreen .............................................................................................................................................................. 116

FILE OBJECTS ................................................................................................................. 122

roAppendFile ................................................................................................................................................................. 122

roCreateFile ................................................................................................................................................................... 124

roReadFile ..................................................................................................................................................................... 126

roReadWriteFile ............................................................................................................................................................. 128

HASHING AND STORAGE OBJECTS ............................................................................. 130

roBlockCipher ................................................................................................................................................................ 130

roBrightPackage ............................................................................................................................................................ 133

roDiskErrorEvent ........................................................................................................................................................... 136

roDiskMonitor ................................................................................................................................................................ 137

roHashGenerator ........................................................................................................................................................... 139

roPassKey ..................................................................................................................................................................... 140

roRegistry ...................................................................................................................................................................... 142

roRegistrySection .......................................................................................................................................................... 143

roSqliteDatabase ........................................................................................................................................................... 145

roSqliteEvent ................................................................................................................................................................. 148

roSqliteStatement .......................................................................................................................................................... 149

roStorageAttached, roStorageDetached ........................................................................................................................ 156

roStorageHotplug .......................................................................................................................................................... 158

roStorageInfo ................................................................................................................................................................. 160

CONTENT MANAGEMENT OBJECTS ............................................................................. 162

roAssetCollection ........................................................................................................................................................... 162

roAssetFetcher .............................................................................................................................................................. 165

roAssetFetcherEvent ..................................................................................................................................................... 169

roAssetFetcherProgressEvent ....................................................................................................................................... 174

roAssetPool ................................................................................................................................................................... 175

roAssetPoolFiles ............................................................................................................................................................ 177

roAssetRealizer ............................................................................................................................................................. 179

roAssetRealizerEvent .................................................................................................................................................... 181

roSyncSpec ................................................................................................................................................................... 183

NETWORKING OBJECTS ................................................................................................ 185

roDatagramSender, roDatagramReceiver, roDatagramSocket, roDatagramEvent ....................................................... 185

roHttpEvent .................................................................................................................................................................... 190

roHttpServer .................................................................................................................................................................. 192

roMediaServer ............................................................................................................................................................... 197

roMediaStreamer ........................................................................................................................................................... 199

roMediaStreamerEvent .................................................................................................................................................. 201

roMimeStream ............................................................................................................................................................... 202

roMimeStreamEvent ...................................................................................................................................................... 203

roNetworkAdvertisement ............................................................................................................................................... 204

roNetworkAttached, roNetworkDetached ....................................................................................................................... 206

roNetworkConfiguration ................................................................................................................................................. 207

roNetworkHotplug .......................................................................................................................................................... 216

roNetworkStatistics ........................................................................................................................................................ 217

roRssParser, roRssArticle ............................................................................................................................................. 219

roRtspStream ................................................................................................................................................................ 221

roShoutcastStream ........................................................................................................................................................ 222

roShoutcastStreamEvent ............................................................................................................................................... 223

roSnmpAgent ................................................................................................................................................................. 224

roSnmpEvent ................................................................................................................................................................. 225

roStreamByteEvent ....................................................................................................................................................... 227

roStreamConnectResultEvent ....................................................................................................................................... 228

roStreamEndEvent ........................................................................................................................................................ 229

roStreamLineEvent ........................................................................................................................................................ 230

roSyncManager ............................................................................................................................................................. 231

roSyncManagerEvent .................................................................................................................................................... 235

roTCPConnectEvent ...................................................................................................................................................... 236

roTCPServer .................................................................................................................................................................. 237

roTCPStream ................................................................................................................................................................. 238

roUrlStream ................................................................................................................................................................... 240

roUrlTransfer ................................................................................................................................................................. 241

roUrlEvent ...................................................................................................................................................................... 250

INPUT/OUTPUT OBJECTS ............................................................................................... 255

roCecInterface ............................................................................................................................................................... 255

roCecRxFrameEvent, roCecTxCompleteEvent ............................................................................................................. 256

roChannelManager ........................................................................................................................................................ 258

roControlPort ................................................................................................................................................................. 266

roControlUp, roControlDown ......................................................................................................................................... 272

roGpioControlPort, roGpioButton ................................................................................................................................... 273

roIRReceiver .................................................................................................................................................................. 275

roIRDownEvent, roIRRepeatEvent, roIRUpEvent .......................................................................................................... 277

roIRTransmitter .............................................................................................................................................................. 278

roIRRemote ................................................................................................................................................................... 279

roIRRemotePress .......................................................................................................................................................... 281

roKeyboard, roKeyboardPress ...................................................................................................................................... 283

roMessagePort .............................................................................................................................................................. 286

roSequenceMatcher ...................................................................................................................................................... 288

roSequenceMatchEvent ................................................................................................................................................ 291

roSerialPort .................................................................................................................................................................... 292

SYSTEM OBJECTS .......................................................................................................... 295

roDeviceInfo .................................................................................................................................................................. 295

roResourceManager ...................................................................................................................................................... 298

roSystemLog ................................................................................................................................................................. 300

DATE AND TIME OBJECTS ............................................................................................. 302

roDateTime .................................................................................................................................................................... 302

roSystemTime ............................................................................................................................................................... 304

roTimer .......................................................................................................................................................................... 309

roTimerEvent ................................................................................................................................................................. 313

roTimeSpan ................................................................................................................................................................... 314

LEGACY OBJECTS .......................................................................................................... 315

roRtspStreamEvent ....................................................................................................................................................... 315

roSyncPool .................................................................................................................................................................... 316

roSyncPoolEvent ........................................................................................................................................................... 319

roSyncPoolFiles ............................................................................................................................................................. 320

roSyncPoolProgressEvent ............................................................................................................................................. 321

Change Log ...................................................................................................................... 322

4.4.x, 4.2.x, 3.10.x ......................................................................................................................................................... 322

4.6.x, 4.4.x, 3.10.x ......................................................................................................................................................... 323

4.7.x ............................................................................................................................................................................... 324

4.8.x ............................................................................................................................................................................... 328

5.0.x ............................................................................................................................................................................... 330

5.1.x ............................................................................................................................................................................... 331

INTRODUCTION

BrightSign players use a standardized library of BrightScript objects to expose functionality for public software development. To publish a new API for interacting with BrightSign hardware, we create a new BrightScript object.

This Object Reference Manual describes the BrightScript object architecture in two main sections:

• How to use BrightScript objects (as a script writer)

• How objects are defined for BrightSign players

INTERFACES AND METHODS OVERVIEW

Every BrightScript object consists of one or more "interfaces." An interface consists of one or more "methods." For example, the roVideoPlayer object has several interfaces, including ifSetMessagePort. The interface ifSetMessagePort has one method: SetPort().

Example: The abstract interface ifSetMessagePort is exposed and implemented by both the roControlPort and the roVideoPlayer objects. Once the SetPort() method is called, these objects will send their events to the supplied

message port. This is discussed more in the Event Loops section below.

p = CreateObject("roMessagePort")

video = CreateObject("roVideoPlayer")

gpio = CreateObject("roControlPort", "BrightSign")

gpio.SetPort(p)

video.SetPort(p)

The above syntax makes use of a shortcut provided by the language: The interface name is optional, unless it is needed to resolve name conflicts. For example, the following two lines of code carry out the exact same function:

gpio.SetPort(p)

gpio.ifSetMessagePort.SetPort(p)

BrightScript Objects consist only of interfaces, and interfaces define only methods. There is no concept of a "property" or variable at the object or interface level. These must be implemented as “set” or “get” methods in an interface.

Classes

A "class name" is used to create a BrightScript object. For example, the class name for a video playback instance is roVideoPlayer, so, to initialize a video playback instance, you would use code similar to the following:

video = CreateObject("roVideoPlayer")

Note that “video” can be any name that follows the syntax outlined in the next section.

Object and Class Name Syntax

Class names have the following characteristics:

• Must start with an alphabetic character (a – z).

• May consist of alphabetic characters, numbers, or the "_" (i.e. underscore) symbol.

• Are not case sensitive.

• May be of any reasonable length.

Zones

With the BrightSign Zones feature, you can divide the screen into rectangles and play different content in each rectangle.

Depending on the BrightSign model, zones can contain video, images, HTML content, audio, a clock, or text. There can be only one video zone per screen for all HD and LS models. However, there can be multiple zones of other types on the screen. A text zone can contain simple text strings or can be configured to display an RSS feed in a ticker-type display.

To enable zone functionality, the following global function must be called in the script:

EnableZoneSupport(enable As Boolean) As Void

When zones are enabled, the image layer is on top of the video layer by default. The default behavior can be modified using the roVideoMode.SetGraphicsZOrder() method.

When zones are not enabled, the image layer is hidden whenever video is played, and the video layer is hidden whenever images are played.

Event Loops

When writing anything more than a very simple script, an "event loop" will need to be created. Event loops typically have the following structure:

1. Wait for an event.

2. Process the event.

3. Return to step 1.

An event can be any number occurrences: a button has been pressed; a timer has been triggered; a UDP message has been received; a video has finished playing back; etc.

By convention, event scripting for BrightScript objects follows this work flow:

1. An object of the type roMessagePort is created by the user’s script.

2. Objects that can send events (i.e. those that support the ifMessagePort/ifSetMessagePort interface) are instructed to send their events to this message port using the SetPort() method. You can set up multiple message ports and have each event go to its own message port, but it is usually simpler to create one message port and have all the events sent to this one port.

3. The script waits for an event. The actual function to do this is ifMessagePort.WaitMessage(), but the built-in Wait() statement in BrightScript allows you to do this more easily.

4. If multiple event types are possible, your script should determine which event the wait function received, then process it. The script then jumps back to the wait.

An event can be generated by any BrightScript Object. For example, the class roControlPort sends events of type roControlDown and roControlUp. The roControlDown implements the ifInt interface, which allows access to an integer. An event loop needs to be aware of the possible events it can receive and be able to process them.

BrightSign Object Library

The following chapters provide definitions for objects that can be used in BrightScript. A brief description, a list of interfaces, and the member functions of the interfaces are provided for each object class.

While most BrightScript objects have self-contained sections in this chapter, some objects are grouped in the same section if they are closely related or depend on one another for functionality.

BRIGHTSCRIPT CORE OBJECTS

roArray

This object stores objects in a continuous array of memory locations. Since an roArray contains BrightScript components, and there are object wrappers for most intrinsic data types, entries can either be different types or all of the same type.

Object Creation: The roArray object is created with two parameters.

CreateObject("roArray", size As Integer, resize As Boolean)

• size: The initial number of elements allocated for an array.

• resize: If true, the array will be resized larger to accommodate more elements if needed. If the array is large, this

process might take some time.

The dim statement may be used instead of the CreateObject function to create a new array. The dim statement is sometimes advantageous because it automatically creates array-of-array structures for multi-dimensional arrays.

Interfaces: ifArray, ifEnum, ifArrayGet, ifArraySet

The ifArray interface provides the following:

• Peek() As Dynamic: Returns the last (highest index) array entry without removing it.

• Pop() As Dynamic: Returns the last (highest index) entry and removes it from the array.

• Push(a As Dynamic): Adds a new highest index entry to the end of the array

• Shift() As Dynamic: Removes index zero from the array and shifts all other entries down by one unit.

• Unshift(a As Dynamic): Adds a new index zero to the array and shifts all other entries up by one unit.

• Delete(a As Integer) As Boolean: Deletes the indicated array entry and shifts all above entries down by one unit.

• Count() As Integer Returns the index of the highest entry in the array plus one (i.e. the length of the array).

• Clear(): Deletes every entry in the array.

• Append(a As Object): Appends one roArray to another. If the passed roArray contains entries that were never

set to a value, they are not appended. Note: The two appended objects must be of the same type.

The ifEnum interface provides the following:

• Reset(): Resets the position to the first element of enumeration.

• Next() As Dynamic: Returns a typed value at the current position and increment position.

• IsNext() As Boolean: Returns True if there is a next element.

• IsEmpty() As Boolean: Returns True if there is not an exact statement.

The ifArrayGet interface provides the following:

• GetEntry(a As Integer) As Dynamic: Returns an array entry of a given index. Entries start at zero. If an entry that has not been set is fetched, Invalid is returned.

The ifArraySet interface provides the following:

• SetEntry(a As Integer, b As Dynamic): Sets an entry of a given index to the passed type value.

roAssociativeArray

An associative array (also known as a map, dictionary, or hash table) that allows objects to be associated with string keys.

This object is created with no parameters:

CreateObject("roAssociativeArray")

Interfaces: ifEnum, ifAssociativeArray

The ifEnum interface provides the following:

• Reset(): Resets the position to the first element of enumeration.

• Next() As Dynamic: Returns the typed value at the current position and increment position.

• IsNext() As Boolean: Returns True if there is a next element.

• IsEmpty() As Boolean: Returns True if there is not a next element.

The ifAssociativeArray interface provides the following:

• AddReplace(key As String, value As Object) As Void: Adds a new entry to the array, associating the supplied object with the supplied string. Only one object may be associated with a string, so any existing object is discarded.

• Lookup(key As String) As Object: Looks for an object in the array associated with the specified string. If there is no object associated with the string, then this method will return Invalid.

• DoesExist(key As String) As Boolean: Looks for an object in the array associated with the specified string. If there is no associated object, then False is returned. If there is such an object, then True is returned.

• Delete(key As String) As Boolean: Looks for an object in the array associated with the specified string. If there is such an object, then it is deleted and True is returned. If not, then False is returned.

• Clear As Void: Removes all objects from the associative array.

• SetModeCaseSensitive(): Makes all subsequent actions case sensitive. All roAssociativeArray lookups are case insensitive by default.

• LookupCi(a As String) As Dynamic: Looks for an object in the array associated with the specified string. This method functions similarly to Lookup(), with the exception that key comparisons are always case insensitive, regardless of case mode.

• Append(a As Object): Appends a second associative array to the first.

Example:

aa = CreateObject("roAssociativeArray")

aa.AddReplace("Bright", "Sign")

aa.AddReplace("TMOL", 42)

print aa.Lookup("TMOL")

print aa.Lookup("Bright")

The above script produces the following:

Sign

roBoolean

This is the object equivalent for the Boolean intrinsic type. It is useful in the following situations:

• When an object is needed instead of an intrinsic value. For example, if a Boolean is added to roList, it will be

automatically wrapped in an roBoolean object by the language interpreter. When a function that expects a BrightScript component as a parameter is passed a Boolean, BrightScript automatically creates the equivalent BrightScript component.

• When any object exposes the ifBoolean interface. That object can then be used in any expression that expects an

intrinsic value.

Interfaces: ifBoolean

The ifBoolean interface provides the following:

• GetBoolean() As Boolean

• SetBoolean(a As Boolean)

roByteArray

This object contains functions for converting strings to or from a byte array, as well as to or from ASCII hex or ASCII base64. Note that if you are converting a byte array to a string, and the byte array contains a zero, the string conversion will end at that point.

The byte array will automatically resize to become larger as needed. If you wish to disable this behavior, use the SetResize() method. If an uninitialized index is read, Invalid is returned.

Since roByteArray supports the ifArray interface, it can be accessed with the array [] operator. The byte array is always accessed as unsigned bytes while this interface is being used. This object also supports the ifEnum interface, and so can be used with a FOR EACH statement.

Interfaces: ifByteArray, ifArray, ifArrayGet, ifEnum, ifArraySet

See roArray for a description of ifArray, ifArrayGet, ifEnum and ifArraySet.

The ifByteArray interface provides the following:

• WriteFile(file_path As String) As Boolean: Writes the bytes contained in the byte array to the specified file. This method returns True if successful.

• WriteFile(file_path As String, start_index As Integer, length As Integer) As Boolean: Writes a subset of the bytes contained in the byte array to the specified file. This method writes length bytes, beginning at start_index of the byte array.

• ReadFile(file_path As String) As Boolean: Reads the specified file into the byte array. This operation will discard any data currently contained in the byte array.

• ReadFile(file_path As String, start_index As Integer, length As Integer) As Boolean: Reads a section of the specified file into the byte array. This method reads length bytes, beginning at start_index of the file. This operation will discard any data currently contained in the byte array.

• AppendFile(file_path As String) As Boolean: Appends the contents of the byte array to the specified file.

• SetResize(minimum_allocation_size As Integer, autoresize As Boolean): Expands the size of the byte array to the minimum_allocation_size if it is less than the minimum_allocation_size. This method also accepts a Boolean parameter that specifies whether the byte array should be resized automatically or not.

• ToHexString() As String: Returns a hexadecimal string representation of the contents of the byte array. Each byte is represented as two hex digits.

• FromHexString(hex_string As String): Writes the contents of the passed hexadecimal string to the byte array. The passed string must contain an even number of hex digits. This operation will discard any data currently contained in the byte array.

• ToBase64String() As String: Returns the contents of the byte array as a base64-formatted string.

• FromBase64String(base_64_string As String): Writes the contents of a valid base64-formatted string to

the byte array. This operation will discard any data currently contained in the byte array.

• ToAsciiString() As String: Returns the contents of the byte array as an ASCII-formatted string.

• FromAsciiString(a As String): Writes the contents of a valid ASCII-formatted string to the byte array. This

operation will discard any data currently contained in the byte array.

• GetSignedByte(index As Integer) As Integer: Returns the signed byte at the specified zero-based index in the byte array. To read an unsigned byte within a byte array, use the ifArrayGet.GetEntry() method or the [] array operator.

• GetSignedLong(index As Integer) As Integer: Retrieves the integer located at the specified long-word index of the byte array. Note that this method cannot accept a byte index as its parameter.

• IsLittleEndianCPU() As Boolean: Returns True if the CPU architecture is little-endian.

roDouble, roIntrinsicDouble

Interfaces: ifDouble

The ifDouble interface provides the following:

GetDouble() As Double

SetDouble(a As Double)

roFunction

Interfaces: ifFunction

• GetSub() As Function

• SetSub(value As Function)

roGlobal

This object provides a set of standard, module-scope functions that are stored in the global object. If one of these global functions is referenced, the compiler directs the runtime to call the appropriate global object member.

Note: Global trigonometric functions accept and return values in radians, not degrees.

Interfaces: ifGlobal

The ifGlobal interface provides the following:

• CreateObject(name As String) As Object: Creates a BrightScript object corresponding to the specified class name. This method returns invalid if object creation fails. Some objects have optional parameters in their constructor, which must be passed after the class name. Example:

sw = CreateObject("roGpioControlPort")

serial = CreateObject("roSerialPort", 0, 9600)

• RestartScript(): Exits the current script. The system then scans for a valid autorun file to run.

• RestartApplication(): Restarts the BrightSign application.

• Sleep(milliseconds As Integer): Instructs the script to pause for a specified amount of time without

wasting CPU cycles. The sleep interval is specified in milliseconds.

• asc(letter As String) As Integer: Returns the ASCII code for the first character of the specified string. A null-string argument will cause an error.

• chr(chr As Integer) As String: Returns a one-character string containing a character reflected by the specified ASCII or control. For example, because quotation marks are normally used as string delimiters, you can pass ASCII code 34 to this function to add quotes to a string.

• len(target_string As String) As Integer: Returns the number of characters in a string.

• str(value As Double) As String: Converts a specified float value to a string. This method also returns a string equal to the character representation of a value. For example, if "A" is assigned a value of 58.5, then calling str(A) will return "58.5" as a string.

• strI(value As Integer) As String: Converts a specified integer value to a string. This method also returns a string equal to the character representation of a value. For example, if "A" is assigned a value of 58.5, then calling stri(A) will return "58" as a string.

• val(target_string As String) As Double: Returns a number represented by the characters in the string argument. This is the opposite of the str() function. For example, if "A" is assigned the string "58", and "B" is assigned the string "5", then calling val(A+"."+B) will return the float value 58.5.

• abs(x As Double) As Double: Returns the absoule vale of the argument x.

• atn(x As Double) As Double: Returns the arctangent (in radians) of the argument x (i.e. Atn(x) returns "the

angle whose tangent is x"). To get the arctangent in degrees, multiply Atn(x) by 57.29578.

• csng(x As Integer) As Float: Returns a single-percision float representation of the argument x.

• cdbl(x As Integer) As Double: Returns a double-percision float representation of the argument x.

• cint(x As Double) As Integer: Returns an integer representation of the argument x by rounding to the

nearest whole number.

• cos(x As Double) As Double: Returns the cosine of the arugment x. The argument must be in radians. To obtain the cosine of x when x is in degrees, use Cos(x*.01745329).

• exp(x As Double) As Double: Returns the natural exponential of x. This is the inverse of the log() function.

• fix(x As Double) As Integer: Returns a truncated representation of the argument x. All digits to the right of

the decimal point are removed so that the resultant value is an integer. For non-negative values of x, fix(x) is equal to int(x). For negative values of x, fix(x) is equal to int(x)+1.

• int(x As Double) As Integer: Returns an integer representation of the argument x using the largest whole number that is not greater than the argument. For example, int(2.2) returns 2, while fix(-2.5) returns -3.

• log(x As Double) As Double: Returns the natural logarithm of the argument x(i.e. loge(x)). This is the inverse of the exp() function. To find the logarithm of a number to a base b, use the following formula:

logb(x) = loge(x)/loge(b).

• sgn(x As Double) As Integer: Returns an integer representing how the float argument x is signed: -1 for negative, 0 for zero, and 1 for positive.

• sgnI(x As Integer) As Integer: Returns an integer representing how the integer argument x is signed: -1 for negative, 0 for zero, and 1 for positive.

• sin(x As Double) As Double: Returns the sine of the argument x. The argument must be in radians. To obtain the sine of x when x is in degrees, use sin(x*.01745329).

• tan(x As Double) As Double: Returns the tangent of the argument x. The argument must be in radians. To obtain the tangent of x when x is in degrees, use tan(x*.01745329).

• sqr(x As Double) As Double: Returns the square root of the argument x. This function is the same as x^(1/2), but calculates the result faster.

• Left(target_string As String, n As Integer) As String: Returns the first n characters of the specified string.

• Right(target_string As String, n As Integer) As String: Returns the last n characters of the specified string.

• StringI(n As Integer, character As Integer) As String: Returns a string composed of a character symbol repeated n times. The character symbol is passed to the method as an ASCII code integer.

• String(n As Integer, character As String) As String: Returns a string composed of a character symbol repeated n times. The character symbol is passed to the method as a string.

• Mid(target_string As String, start_position As Integer, length As Integer) As String: Returns a substring of the target string. The first integer passed to the method specifies the starting position of the substring, and the second integer specifies the length of the substring. The start position of a string begins with 1.

• instr(start_position As Integer, search_text As String, substring_to_find As String) As Integer: Returns the position of a substring within a string. This function is case sensitive and returns 0 if the specified substring is not found. The start position of a string begins with 1.

• GetInterface(object As Object, ifname As String) As Interface: Returns a value of the type Interface. All objects have one or more interfaces. In most cases, you can skip interface specification when calling an object component. This will not cause problems as long as the method names within a function are unique.

• Wait(timeout As Integer, port As Object) As Object: Instructs the script to wait on an object that has an ifMessagePort interface. This method will return the event object that was posted to the message port. If the timeout is specified as zero, Wait() will wait indefinitely; otherwise, Wait() will return Invalid after the specified number of milliseconds if no messages have been received.

Example:

p = CreateObject("roMessagePort")

sw = CreateObject("roGpioControlPort")

sw.SetPort(p)

msg=wait(0, p)

print type(msg) ' should be roGpioButton

print msg.GetInt() ' button number

• ReadAsciiFile(file_path As String) As String: Reads the specified text file and returns it as a string.

• WriteAsciiFile(file_path As String, buffer As String) As Boolean: Creates a text file at the

specified file path. The text of the file is passed as the second parameter. This method cannot be used to edit files: A preexisting text file will be overwritten if it has the same name and directory path as the one being created.

Note: The roCreateFile object provides more flexibility if you need to create or edit files.

• ListDir(path As String) As Object: Returns an roList object containing the contents of the specified directory path. File names are converted to all lowercase.

• MatchFiles(path As String, pattern_in As String) As Object: Takes a directory to look in (it can be as simple as "." or "/") and a pattern to be matched and then returns an roList containing the results. Each listed result contains only the part of the filename that is matched against the pattern, not the full path. The match is only applied in the specified directory; you will get no results if the pattern contains a directory separator. The pattern is a case insensitive wildmat expression. It may contain the following special characters:

o ? -- Matches any single character. o * -- Matches zero or more arbitrary characters.

o […]-- Matches any single character specified within the brackets. The closing bracket is treated as a

member of the character class if it immediately follows the opening bracket (i.e. "[]]" matches a single closed bracket). Within this class, "-" can be used to specify a range unless it is the first or last character (e.g. "[ACf-h"] is equivalent to "[ABCfgh]"). A character class may be negated by specifying "^" as the first character. To match a literal of this character, place it elsewhere in the class.

Note: The special characters "?", "*", and "[" lose their function if preceded by a single "\", and a single "\" can

be matched using "\\".

• LCase(target_string As String) As String: Converts the specified string to all lower case.

• UCase(target_string As String) As String: Converts the specified string to all upper case.

• DeleteFile(file_path As String) As Boolean: Deletes the file at the specified file path. This method

returns False if the delete operation fails or if the file does not exist.

• DeleteDirectory(diretory As String) As Boolean: Deletes the specified directory. This method will recursively delete any files and directories that are necessary for removing the specified directory. This method returns False if it fails to delete the directory, but it may still delete some of the nested files or directories.

• CreateDirectory(directory As String) As Boolean: Creates the specified directory. Only one directory can be created at a time. This method returns True upon success and False upon failure.

• RebootSystem(): Causes a soft reboot.

• ShutdownSystem()

• UpTime(dummy As Integer) As Float: Returns the uptime of the system (in seconds) since the last reboot.

• FormatDrive(drive As String, fs_type As String) As Boolean: Formats the specified drive using

one of the file systems listed below. This function returns True upon success and False upon failure:

o vfat (DOS/Windows file system): Readable and writable by Windows, Linux, and MacOS. o ext2 (Linux file system): Writable by Linux and readable by Windows and MacOS with additional software. o ext3 (Linux file system): Writable by Linux and readable by Windows and MacOS with additional software.

This file system uses journaling for additional reliability.

• EjectDrive(drive As String) As Boolean: Ejects the specified drive (e.g. "SD:") and returns True if successful. If the script is currently accessing files from the specified drive, the ejection process will fail.

• CopyFile(source As String, destination As String) As Boolean: Copies the file at the specified source file-path name to the specified destination file-path name. The function returns True if successful and False in the event of failure.

• MoveFile(a As String, b As String) As Boolean: Moves the specified source file to the specified destination. The function returns True if successful and False in the event of failure.

Note: Both path names must be on the same drive.

• strtoi(target_string As String) As Integer: Converts the target string to an integer. Any non-integer characters (including decimal points and spaces), and any numbers to the right of a non-integer character, will not be part of the integer output.

• rnd(a As Dynamic) As Dynamic

• RunGarbageCollector() As roAssociativeArray: Destroys objects that are currently in a state of circular

reference counting. BrightScript normally removes any objects that become unreferenced as part of its automated garbage collection algorithm. However, objects that reference each other will never reach a reference count of zero, and will need to be destroyed manually using this method. This method is useful when destroying old presentation data structures and generating a new presentation. This method returns an associative array outlining the results of the garbage-collection process.

• GetDefaultDrive() As String: Returns the current default drive complete with a trailing slash. When running autorun.brs, the drive containing the autorun is designated as the current default.

• SetDefaultDrive(a As String): Sets the current default drive, which does not need to include a trailing slash. This method does not fail; however, if the specified default drive does not exist, it will not be possible to retrieve anything.

• EnableZoneSupport(a As Boolean)

• EnableAudioMixer(a As Boolean)

• Pi() As Double: Returns the value of pi as a double-precision floating-point number.

• ParseJson(json_string As String) As Object: Parses a string formatted according to the RFC4627

standard and returns an equivalent BrightScript object, which can consist of the following: Booleans, integers,

floating point numbers, strings, roArray objects, and roAssociativeArray objects. The ParseJson() method has the following properties:

o Invalid will be returned if the string is not syntactically correct. o Any roAssociativeArray objects that are returned will be case sensitive. o An error will be returned if an roArray or roAssociativeArray is nested more than 256 levels deep.

Example: The following script demonstrates how to use ParseJson() to process a JSON object containing the titles and URLs of a set of images.

JSON Script

{

"photos" : [

{

"title" : "View from the hotel",

"url" : "http://example.com/images/00012.jpg"

{

"title" : "Relaxing at the beach",

"url" : "http://example.com/images/00222.jpg"

{

"title" : "Flat tire",

"url" : "http://example.com/images/00314.jpg"

}

]

}

BrightScript

BrightSign Object FW 5.1 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual