borg

Name

borg - control and interact with the Android OS. Part of AndroWish.

Synopsis

: borg cmd ?arg …?

Description

This command integrates the capabilities of Tcl/Tk with an Android OS by way of several subcommands. These allow Tcl/Tk to go where it has never gone before by querying and controlling Bluetooth functionality, OS notifications (including device vibration and even speach), location information, etc.

Bluetooth-Related Commands

borg bluetooth subcmd

borg bluetooth devices: Returns a list suited for the "array set" command containing the Bluetooth address and friendly name of all paired Bluetooth devices.

borg bluetooth state: Returns the current Bluetooth state: on or off.

borg bluetooth scanmode: Returns the current Bluetooth scan mode (off, passive, visible, connectable, or on).

borg bluetooth myaddress: Returns the Bluetooth address of the local default Bluetooth adapter.

borg remoteaddress address: Returns the friendly name for the given Bluetooth address.

Network-Related Commands

borg networkinfo: Returns the current state of the network: none, wifi, mobile gsm, etc.

Desktop-Related Commands

borg shortcut subcmd

borg shortcut add name-of-shortcut script-to-run ?png-icon-as-base-64-string?: Adds an icon to the desktop, with the name-of-shortcut specified. The script, specified as script-to-run must use an absolute path must be readable by the user id under which the AndroWish package has been registered by the Android installer. The last (optional) parameter png-icon-as-base-64-string allows the icon graphic to be specified. If not provided, the AndroWish icon (Aladdin's lamp) is used.

borg shortcut delete name-of-shortcut: Deletes an icon from desktop (depends on Android launcher support).

Notification-Related Commands

borg notification add id title text: Adds a notification with title and text into the Android notification area. The integer id, specified by the caller, is used to identify the notification on deletion.

borg notification delete ?id?: Deletes a notification identified that was created with the id specified. If no id is provided, all notifications are deleted.

borg vibrate ms: Turns on the vibration motor for integer ms milliseconds.

borg beep: Plays the notification sound.

borg speak text ?lang pitch rate?: Gets the Android to read out the string text. Optional parameter lang is the language code for the spoken language, e.g. en, en_US, de, etc. Optional parameters pitch and rate control the voice and speed as float values. For more information, see http://developer.android.com/reference/android/speech/tts/TextToSpeech.html

borg stopspeak: Stops speech output.

borg isspeaking: Returns true or false depending on state of speech output.

borg endspeak: Stops speech output and releases system resources.

borg toast text ?flag?: Displays a text notification text for a short period of time. The duration of that display is somewhat longer when flag is specified as true.

borg spinner on|off: Displays or withdraws a spinner (rotating symbol indicating busy state) depending on argument.

Location-Related Commands

borg location subcmd

borg location start ?minrate-in-ms? ?min-dist-in-m?: Begins acquiring location data via the Android OS (which may choose to use GPS, network info, etc.).

borg location stop: Ends location data acquisition.

borg location get: Returns the location data (as a dictionary, suitable for array set) where the key is the location source. Location updates trigger a virtual event <<LocationUpdate>> (currently untested) that is sent to all toplevel widgets. These toplevel event-handlers should, in turn, invoke borg location get to refresh their knowledge.

System-Related Commands

borg displaymetrics: Returns information about the display in a dictionary (suitable for array set), e.g. display resolution, pixel density. See http://developer.android.com/reference/android/util/DisplayMetrics.html for details.

borg osbuildinfo: Returns information about the operating system and device in a dictionary (form suitable for array set), e.g. Android API level, version, device name, manufacturer etc. See http://developer.android.com/reference/android/os/Build.html for details.

General

borg activity action uri type ?categories? ?arguments? ?callback?: This a very flexible command that allows extensive access to the Android OS and other applications. categories and arguments are optional lists. callback is the name of the procedure that is evaluated when the activity action is complete. arguments are key-value pairs where the values are mapped to Java strings by default. If the key is a 2-element list made up of a data type indicator (int, byte, short, char, long, float, double, Uri) followed by the key, the value is converted to that data type. See below for some examples of this command. (?? categories argument ??)

borg activity Examples

Sample code to open a browser on this wiki:

     borg activity android.intent.action.VIEW https://wiki.tcl-lang.org

Sample code to capture an image (only makes thumbnails - there are resizing problems):

    proc callback {retcode action uri mimetype categories data} {
        if {$retcode == -1} {
            # SUCCESS
            array set result $data
            if {[info exists result(data)]} {
                myphoto configure -data $result(data)
            }
        }
    }
    package require Img
    image create photo myphoto
    borg activity android.media.action.IMAGE_CAPTURE {} {} {} {} callback

Sample code to capture an image, which works better but requires a file on external storage:

    proc callback {filename retcode action uri mimetype categories data} {
        if {$retcode == -1} {
            # SUCCESS
            myphoto configure -file $filename
            catch {file delete -force $filename}
        }
    }
    package require Img
    image create photo myphoto
    set filename [file join $env(EXTERNAL_FILES) myphoto.jpeg]
    borg activity android.media.action.IMAGE_CAPTURE {} {} {} \
       [list {Uri output} file://$filename] [list callback $filename]

Reading barcodes using the http://code.google.com/p/zxing barcode scanner (which needs to be be installed on your device):

    proc barcode_read {code action uri type cat data} {
        array set result $data
        if {[info exists result(SCAN_RESULT)]} {
            # that is the barcode
            # result(SCAN_RESULT_FORMAT) is the barcode format
        }
    }

    borg activity com.google.zxing.client.android.SCAN {} {} {} {} barcode_read

Open phone application with given number

    borg activity android.intent.action.DIAL tel:12345 {}

Category Command

AndroWish