- NAME
- DESCRIPTION
- OPTIONS
- This tool's API

- ReadProperty

- Inputs to ReadProperty
- Outputs from ReadProperty
- Example of ReadProperty

- ReadPropertyMultiple

- Inputs to ReadPropertyMultiple
- Outputs from ReadPropertyMultiple
- Example of ReadPropertyMultiple

- WriteProperty

- Inputs to WriteProperty
- Outputs from WriteProperty
- Example of WriteProperty

- TimeSync

- Inputs to TimeSync
- Outputs from TimeSync
- Example of TimeSync

- Log

- Inputs to Log
- Example of Log

- SilenceLog

- Inputs to SilenceLog
- Outputs from SilenceLog
- Example of SilenceLog

- Retry

- Inputs to Retry
- Outputs from Retry
- Example of Retry

# NAME

bacnet.pl - Scriptable BACnet communications

# DESCRIPTION

This is a tool for scriptable BACnet communication. Users can write their own scripts using standard Perl syntax and API defined in this tool to perform desired execution sequences. For details on this tool's API, see Documentation.html. For other Perl documentation, see http://perldoc.perl.org

# OPTIONS

Usage: bacnet.pl [program_options] [-- script_args]

This program executes a script in perl syntax to perform BACnet/IP operations.

     Possible program options:
       --script=s    The script to execute.
       --log=s       The file to log all output.
       --help        This help message.

     Possible environment variables are:
        BACNET_IFACE - set this value to dotted IP address of the interface (see
             ipconfig) for which you want to bind.  Default is the interface which
             Windows considers to be the default (how???).  Hence, if there is only a
             single network interface on Windows, the applications will choose it, and
             this setting will not be needed.
        BACNET_IP_PORT - UDP/IP port number (0..65534) used for BACnet/IP
             communications.  Default is 47808 (0xBAC0).
        BACNET_APDU_TIMEOUT - set this value in milliseconds to change the APDU
             timeout.  APDU Timeout is how much time a client waits for a response from
             a BACnet device.
        BACNET_BBMD_PORT - UDP/IP port number (0..65534) used for Foreign Device
             Registration.  Defaults to 47808 (0xBAC0).
        BACNET_BBMD_TIMETOLIVE - number of seconds used in Foreign Device
             Registration (0..65535). Defaults to 60000 seconds.
        BACNET_BBMD_ADDRESS - dotted IPv4 address of the BBMD or Foreign Device
             Registrar.

# This tool's API

In addition to having all standard Perl flow control, functions, and modules, the this tool provides an API for performing BACnet communication functions.

## ReadProperty

This function implements the ReadProperty service. There are no built in retry mechanisms. NOTE: all enumerations are defined in bacenum.h

### Inputs to ReadProperty

- devideInstance - the instance number of the device we are reading
- objectName - the enumeration for the object name we are reading
- objectInstance - the instance number of the object we are reading
- propertyName - the enumeration for the property name we are reading
- index - Optional (default -1): the index number we are reading from. -1 if not applicable

### Outputs from ReadProperty

- result - the sting result (value or error) for ReadProperty
- isFailure - zero means no failure, non-zero means failure

### Example of ReadProperty

The following example will read AV0.PresentValue from device 1234

        my ($res, $failed) = ReadProperty(1234, 'OBJECT_ANALOG_VALUE', 0, 'PROP_PRESENT_VALUE');

## ReadPropertyMultiple

This function implements the ReadPropertyMultiple service. There are no built in retry mechanisms. NOTE: all enumerations are defined in bacenum.h

### Inputs to ReadPropertyMultiple

- devideInstance - the instance number of the device we are reading
- r_answerList - reference to a list where to store the answers
- list - a list of ReadAccessSpecifications

- objectType - the enumeration for the object name to read from
- objectInstance - the instance number of the object we are reading
- propertyName - the enumeration for the property name we are reading
- index - the index number we are reading from. Use -1 if not applicable

### Outputs from ReadPropertyMultiple

- result - the 'QQQ' delimited concatenated sting result (value or error) for ReadPropertyMultiple. The parsed out result is returned in r_answerList
- isFailure - zero means no failure, non-zero means failure

### Example of ReadPropertyMultiple

The following example will read AV0.PresentValue and AV1.PresentValue from device 1234

        my @RPM_request = ();
        my @RPM_answer = ();
        my $failed;
        push @RPM_request, ['OBJECT_ANALOG_VALUE', 0, 'PROP_PRESENT_VALUE', -1];
        push @RPM_request, ['OBJECT_ANALOG_VALUE', 1, 'PROP_PRESENT_VALUE', -1];
        (undef, $failed) = ReadPropertyMultiple(1234, \@RPM_answer, @RPM_request);

## WriteProperty

This function implements the WriteProperty service. There are no built in retry mechanisms. NOTE: all enumerations are defined in bacenum.h

### Inputs to WriteProperty

- devideInstance - the instance number of the device we are writing
- objectName - the enumeration for the object name we are writing
- objectInstance - the instance number of the object we are writing
- propertyName - the enumeration for the property name we are writing
- tagName - the enumeration for the type of value we are writing. To specify context tags, prepend the tag name with "Cn:" where 'n' is the context number.
- value - the value we are writing
- priority - Optional (default 0): the priority within Priority Array to write at. Use 1-16 when specify priority, 0 to not specify priority.
- index - Optional (default -1): the index within an array we are writing to. Use positive number to indicate index, -1 to not specify index.

### Outputs from WriteProperty

- result - the sting result (value or error) for WriteProperty
- isFailure - zero means no failure, non-zero means failure

### Example of WriteProperty

The following example will write 1.0 to AV0.PresentValue in device 1234

        my ($res, $failed) = WriteProperty(1234, 'OBJECT_ANALOG_VALUE', 0, 'PROP_PRESENT_VALUE', 'BACNET_APPLICATION_TAG_REAL', 1.0);

## TimeSync

This function implements the TimeSync and UTCTimeSync services

### Inputs to TimeSync

- deviceInstanceNumber - the instance number of the device we are reading
- year - Year (i.e. 2011)
- month - Month (i.e. 11 for November)
- day - Day (i.e. 1 for first of month)
- hour - Hour (i.e. 23 for 11pm)
- minute - Minute (i.e. 0-59)
- second - Second (i,e. 0-59)
- utcOffset - Optional: if specified defines the UTC offset and forces UTCTimeSync

### Outputs from TimeSync

- isFailure - zero means no failure, non-zero means failure

### Example of TimeSync

        $isFailure = TimeSync($deviceInstance, $1, $2, $3, $4, $5, $6) unless $isFailure;

## Log

This function prints out to the desired method of logging (STDOUT or file). NewLine characters are not required when making calls to this function. If any NewLine characters are specified, they will be stripped out. To print an empty line, pass in a space as the message. NOTE: This function will honor previous requests to silence the log (see SilcenseLog for details)

### Inputs to Log

- msg - the message to output

### Example of Log

The following example will print out "hello world"

        Log("Hello World");

## SilenceLog

This function requests that all future log messages be either suppressed or enabled.

### Inputs to SilenceLog

- logIsQuiet - zero means print to log, non-zero means supress log

### Outputs from SilenceLog

The previous value of whether or not the log was silenced before caling this function.

### Example of SilenceLog

The following example will print out "hello", but not "world"

        Log("Hello");
        SilenceLog(1);
        Log("World");

## Retry

This function will try to execute the requested command up to specified number of times, awaiting the requested answer, with a specified pause between retries. NOTE: the only functions which can be executed by this function are ones which return two parameres in the form of ($response, $isFailure)

### Inputs to Retry

- r_func - The reference to the function which is to be retried
- r_funcArgs - A reference to an array of arguments for the function to be executed
- desiredOutput - The condition which will terminate the retrying. Can be either a number or a regexp to patch against the $response return of the function
- maxTries - The maximum number of retry attempts before calling it quits
- sleepSeconds - The number of seconds (could be fractional) to wait between retries

### Outputs from Retry

- $resp - The response from the last execution of requested function
- isFailure - zero means no failure, non-zero means failure

### Example of Retry

The following example will execute the ReadProperty function to read a property from an object (see ReadProperty for details on those arguments) with up to $maxRetries retries (with $retryDelay delay between retries) or unitl the desired answer of 42 is received.

        my ($resp, $isFailure) = Retry(
                    \&ReadProperty, [$deviceInstance, 'OBJECT_ANALOG_VALUE', 0, 'PROP_PRESENT_VALUE'],
                    42, $maxRetries, $retryDelay
                  );
        if ($isFailure)
        {
            die "Value was not 42. Last response was '$resp'";
        }

The following example will try to execute a WriteProperty (see that function for details on its arguments) until the write succeeds.

        my ($resp, $isFailure) = Retry(
                    \&WriteProperty, [$deviceInstance, 'OBJECT_ANALOG_VALUE', 0, 'PROP_PRESENT_VALUE', 'BACNET_APPLICATION_TAG_REAL', 42.0],
                    "Acknowledged", $maxRetries, $retryDelay
                  );
        if ($isFailure)
        {
            die "Could not write 42. Last response was '$resp'";
        }