Skip to content

Release_Notes.md

Latest commit

 

History

History
163 lines (127 loc) · 7.15 KB

Release_Notes.md

File metadata and controls

163 lines (127 loc) · 7.15 KB

Botctrl

This release of the botctrl command line management system expands support for controlling Corrade bots from the command line, adding support for many additional Corrade API commands. In addition, the install script installs jq if not already present and installs example scripts in /usr/local/BotControl/examples/.

The release includes the release artifact install which can be used to install the botctrl management system. See the Install botctrl section below for installation instructions. See the repository README for additional info and example botctrl command invocations.

Install botctrl

To install botctrl:

git clone https://github.com/slbotcontrol/BotControl.git
cd BotControl
./install

Or, you can use the curl command to install botctrl with a single command:

curl -fsSL https://raw.githubusercontent.com/slbotcontrol/BotControl/refs/heads/main/install | bash

Alternatively, download the install release artifact and execute it. The install script will clone the repository and install the system:

wget -q https://github.com/slbotcontrol/BotControl/releases/latest/download/install
chmod 755 install
./install

Configure Corrade for use with the botctrl command

In order to use the botctrl command to manage your Corrade bot(s):

  • The HTTP server must be enabled in the Corrade configuration
  • ScriptLanguage must be set to JSON in the Corrade configuration

Example snippet to enable the HTTP server in CorradeConfiguration.xml:

<Servers>
    <HTTPServer>
        <Enable>1</Enable>
        <Prefixes>
            <Prefix>http://+:8082/</Prefix>
        </Prefixes>
    </HTTPServer>
    ...
</Servers>

Set the port number in the Prefix configuration to an open unused port. If you have more than one Corrade bot then use a different port for each.

To set the ScriptLanguage to JSON in CorradeConfiguration.xml:

  <ScriptLanguage>JSON</ScriptLanguage>

Configure botctrl

The botctrl command is installed in /usr/local/bin along with some utility scripts for use with cron or other management systems. These utility scripts will need to be modified to suit your specific needs, configuration and bot names. You can modify the scripts in BotControl/bin/ and re-run ./install.

Add /usr/local/bin to your execution PATH if it is not already included.

Configure botctrl by adding and editing the file ${HOME}/.botctrl.

At a minimum, you must configure your LifeBots developer API key and bot secrets for the LifeBots bots you wish to control using the botctrl command.

The following example entries in $HOME/.botctrl will allow you to control your LifeBots bot named "LifeBots Botname" and a Corrade bot named "Corrade Botname" using the botctrl command:

## Minimum contents of $HOME/.botctrl
#
# LifeBots Developer API Key
export LB_API_KEY='<your-lifebots-api-key>'
# LifeBots bot secret
export LB_SECRET_LifeBots_Botname='<your-bot-secret>'
# Corrade command control via LifeBots
export CORRADE_GROUP="<your-corrade-bot-group-name>"
export CORRADE_PASSW="<your-corrade-bot-group-password>"
export CORRADE_URL="https://your.corrade.server"
# Assuming a reverse proxy is configured for the /corrade/ location
export API_URL_Corrade_Botname="${CORRADE_URL}/corrade/"

Add an entry of the form export LB_SECRET_Firstname_Lastname='<bot-secret>' to $HOME/.botctrl for each of your LifeBots bots.

See example_dot_botctrl for a template to use for this file.

See crontab.in for example crontab entries to schedule bot activities.

Usage

Click here to view the

botctrl command usage message

 
Usage: botctrl [-deih] [-a action] [-A avatar] [-l location] [-n name] [-k apikey] [-C channel] [-c corrade]
  [-D data] [-F filter] [-M message] [-N name] [-O name] [-S subject] [-s secret] [-T text] [-u uuid] [-z num]
Where:
	-a action specifies the API action (sit, teleport, login, ...)
	-l location specifies a location for login and teleport actions
		Default: Last location, teleport action requires a Slurl location
	-n name specifies a Bot name, Default: Easy Islay
	-k apikey specifies an API Key, use environment instead
	-A avatar specifies an avatar UUID for use with giving money or objects
	-C channel specifies the channel for a message [default: 0]
	-c corrade specifies a Corrade bot name to act upon
	-D data specifies a Corrade Manager class member
	-F filter specifies a filter to match when listing attachments
	-M message specifies the message body for a group notice/im
	-N name specifies the name of the recipient of an IM or landmark/notecard
	-O name specifies an attachment object name or outfit name
	-S subject specifies the subject for a group notice
	-s secret specifies a Bot secret, use environment instead
	-T text specifies the notecard text or dialog button text for reply to menus
	-u uuid specifies a UUID for use with actions that require one (e.g. sit)
	-z num specifies a hover height adjustment size [default: -0.05]
		can also be used to specify a payment amount
	-d indicates dryrun mode - tell me what you would do without doing anything
	-e displays a list of supported commands and examples then exits
	-i retrieves Bot details
	-h displays this usage message and exits

Environment:
  Entries in ~/.botctrl can be LB_API_KEY, LB_SECRET, or entries
  of the form LB_SECRET_BOT_NAME in order to support multiple bots
  Entries can specify a Slurl alias. For example:
    export SLURL_club='http://maps.secondlife.com/secondlife/Scylla/226/32/78'
  A Slurl alias can be used with the -l command line argument, e.g. -l club
  Entries can also specify a UUID alias. For example:
    export UUID_Mover='xxxxxxxx-yyyy-zzzz-aaaa-bbbbbbbbbbbb'
  A UUID alias can be used with the -u command line argument, e.g. -u Mover

Examples:
  botctrl  # Displays the status of the default Bot
  botctrl -a login -l Home # Default Bot login to Home location
  botctrl -a touch_prim -n 'Jane Doe' -u Mover # Jane Doe bot touch object with aliased UUID
  botctrl -a stand -n Jane -c John # Jane bot sends the stand command to Corrade bot John
  botctrl -a teleport -l club  # Uses a 'club' location alias defined in .botctrl

Supported Actions
Supported actions for BotControl Configuration:
  bot_alias, loc_alias, slurl_alias, uuid_alias, list_alias, alias
Supported actions common to both Corrade and LifeBots:
  activate_group, attachments, avatar_picks, get_balance, get_outfit, get_outfits, give_inventory,
  give_object, give_money, give_money_object, im, key2name, listinventory, login, logout,
  name2key, notecard_create, rebake, say_chat_channel, send_group_im, send_notice,
  set_hoverheight, sit, stand, status, takeoff, teleport, touch_prim, walkto, wear, wear_outfit
Supported actions for LifeBots only:
  bot_location, reply_dialog, touch_attachment
Supported actions for Corrade only:
  attach, conference, conference_detail, conference_list, createlandmark, currentsim, detach
  fly, flyto, getattachmentspath, getavatarpickdata, getgroupmemberdata, get_hoverheight,
  getmembersonline, getregiontop, getselfdata, inventory cwd, networkmanagerdata