Plugins

From TrekBuddy Wiki

Jump to: navigation, search

I intend to transfer all knowledge abou CMS, HECL etc from the forum here...

Contents

Overview

TrekBuddy has built-in support for HECL [1], modules core and http (since v1.1)

Plugin

Plugin is a HECL script with .hcl file suffix and recognized prefix. As of v1.1, only live. prefix is recognized.

Example: live.leo.hcl

Plugins are placed in plugins folder. CMS scripts are placed in ui-profiles.

Structure

Script contains variables and functions. All plugins run in the same address space, so to avoid name conflict, functions and global variables should prefixed with unique prefix (aka namespace). Years ago we started to use syntax prefix::someName, so let's keep with that.

Example:

var leo::username "cornholio"

Example:

proc leo::onLocationUpdated {} {
   ...
}

Mandatory rules

  1. plugin filename (without prefix and and suffix) MUST match the namespace used in the code. Example: if the plugin filename is live.leo.hcl, namespace for variables and functions MUST be leo. CMS plugins do not (need to) conform to this naming conventions due to historical reasons :).

Management

Menu->Live opens a list of all plugins, with status icon for each plugin. Status icons are:

  • grey - plugin is not enabled. Important! User can still open plugin screen and invoke custom actions (if plugin provides any).
  • green - plugin is enabled AND there was no error during execution of an event AND plugin reports "OK" status
  • red - execution of some event failed OR plugin does not report "OK" status

If plugin provides any custom actions, they will be available as standard menu options. The result of invocation is displayed in a dialog window.

Configuration

In Settings->Plugins, user can enable plugin, and configure it. Configuration is persistent. Configurable options of a plugin are defined by getOptions plugin callback. If you change name or order of the options, plugin will be loaded but configuration will not be set.

Confirm any change in plugin configuration with OK menu options.

Types of plugins

Type of the plugin is denoted by file prefix:

  • live

CMS

Special kind of plugins. Already supported for many years. Scripts run in a separate interpreter. Not yet integrated to standard plugin mechanism (configuration, management).

Forum section: [2]

Available system variables: TODO

TODO; move info (CMS design, variables etc) from the forum here

Events

All event handlers are optional.

  • onTrackingStart
  • onTrackingStop
  • onLocationUpdated
  • onKeyPress

Live

Live plugins can use available CMS system variables (cms::lat etc).

Events

All event handlers are optional.

  • onTrackingStart
  • onTrackingStop
  • onLocationUpdated

Callbacks

All callbacks are optional, but at least getName and getVersion SHOULD be provided.

  • getName - returns plugin name as string. Used in plugins configuration and also status page.
  • getVersion - returns plugin version as string. It is used in plugins configuration and also status page.
  • getOptions - returns list of variables (their names!) that can or should be configurable by the user.
  • getActions - returns list of custom actions (their names!) that the user can invoke from plugin status page.
  • getStatus - returns plugin status as string. "OK" should be returned if everything is OK.
  • getDetail - messages that will be displayed in plugin status page

Online maps

TBD

HECL Extensions

  • misc
    • var - declares global variable. Example: var username "shrek"
    • play - plays sound file from sounds folder
  • math functions
    • | - binary OR. Example: set three [| 1 2]
    • & - binary AND. Example: set two [& 3 2]
    • << - left bit shift. Example: set doubled [<< 2 1]
    • >> - right bit shift. Example: set half [>> 2 1]
  • string functions
    • 0x - return hexadecimal representation of integral number (without leading 0x). Example: set hexdum [0x 128]

Samples

CMS demo

TODO

LiveTrack24 demo plugin

This has actually been tested :-)

###########################################
#                                         #
# Sample TrekBuddy plugin for LiveTrack24 #
#                                         #
###########################################

#
# options configurable in TrekBuddy (Settings->Plugins)
#  - see getOptions callback
#

var leo::baseURL http://test.livetrack24.com/track.php
var leo::username "user"
var leo::password "password"
var leo::userID 0
var leo::interval 60

#
# local variables
#

set leo::client "TrekBuddy/LiveTrack24"
set leo::version "1.0"
set leo::sessionID ""
set leo::pid 1
set leo::lastt 0
set leo::lastncode 0
set leo::laststatus ""
set leo::count 0

#
# standard plugin callbacks
#

proc leo::getVersion {} {
    return $leo::version
}

proc leo::getName {} {
    return "LiveTrack 24"
}

proc leo::getStatus {} {
    return "OK"
}

proc leo::getDetail {} {
    return "Packets sent: $leo::count\nLast HTTP call status: $leo::laststatus ($leo::lastncode)"
}

proc leo::getOptions {} {
    return [list leo::baseURL leo::username leo::password leo::userID leo::interval]
}

proc leo::getActions {} {
    return [list leo::DumbAction leo::PingSomeWeb]
}

#
# custom callbacks with dumb names
#  - see getActions callback
#

proc leo::DumbAction {} {
    puts "dumb action"
}

proc leo::PingSomeWeb {} {
    set result [http.geturl http://www.google.com]
    return "Google response: [hget $result status] ([hget $result ncode])"
}

#
# standard tracking events
#

proc leo::onTrackingStart {} {
    # (re)set starting packet id
    set leo::pid 1

    # (re)set counter
    set leo::count 0

    # generate session ID
    set rnd [<< [int [clock time]] 24]
    set rnd [& $rnd 0x7F000000]
    set rnd [| $rnd [& $leo::userID 0x00ffffff]]
    set rnd [| $rnd 0x80000000]
    set leo::sessionID [0x $rnd]
    
    set result [http.geturl $leo::baseURL?leolive=2&sid=$leo::sessionID&pid=$leo::pid&client=$leo::client&v=$leo::version&user=$leo::username&pass=$leo::password]
    set leo::lastncode [hget $result ncode]
    set leo::laststatus [hget $result status]

    #increment packet id
    incr $leo::pid

    #increment counter
    incr $leo::count
}

proc leo::onTrackingStop {} {
    set result [http.geturl $leo::baseURL?leolive=3&sid=$leo::sessionID&pid=$leo::pid&prid=0]
    set leo::lastncode [hget $result ncode]
    set leo::laststatus [hget $result status]

    #increment counter
    incr $leo::count
}

proc leo::onLocationUpdated {} {

    set now [clock seconds]
    set ellapsed [- $now $leo::lastt]

    # send valid position every $leo::interval seconds
    if { and [>= $ellapsed $leo::interval] [> $cms::fix 0] } {

        # use cms values, some needs format adjustment (no decimals, time in seconds)
        set alt [int $cms::alt]
        set sog [int $cms::spd]
        set cog [int $cms::course]
        set tm [/ $cms::time 1000]

        set result [http.geturl $leo::baseURL?leolive=4&sid=$leo::sessionID&pid=$leo::pid&lat=$cms::lat&lon=$cms::lon&alt=$alt&sog=$sog&cog=$cog&tm=$tm]
        set leo::lastncode [hget $result ncode]
        set leo::laststatus [hget $result status]

        # last packet was just sent
        set leo::lastt $now

        # increment packet id
        incr $leo::pid

        #increment counter
        incr $leo::count
    }
}
Personal tools
Navigation