Bluvert

Overview

Description

Bluvert is a small collection of Python scripts which allows you to build up quickly a Bluetooth advertisement or welcome server.
Imagine one of the following situations:

Any of this situations can be realized with Bluvert.

Theory of working

Bluvert uses a more than simple message queuing concept. You can broadcast messages to anyone or an unique device (identified by Bluetooth MAC address). Concept:

  • Create your message file - this can be a text file, an image, an audio file or anything else. This file must be interpreted by the target mobile phone!
  • Add your file to the message queue - specify a broadcast or target address and set a timeout if you want to
  • Toggle on Bluetooth connection on your mobile phone and wait for execution of the Bluvert daemon
  • The message file will be send onto your mobile phone

    • Internal working concept

    Bluvert is based on two parts: the message queue utility and the daemon.
    message queue utility: add-message.py takes a defined input file and put this file into the queue.
    daemon: execute-server.py is the core of Bluvert. It takes a defined CSV file, which includes the current Bluetooth devices in your neighbourhood. After execution the daemon searches for outstanding messages of any of the Bluetooth devices which are defined in the CSV file. If an outstanding message is found, the daemon triggers an external tool. This tool (obexftp) sends the message to the mobile phone. The daemon itself is *not* working in threading mode. The execution of the daemon must be triggered by a cron job or scheduled task.

    Used technologies

    License

    Bluvert is licensed under GPLv2.

    Author

    The scripts are developed by Christopher Klein <goldenhawk[at]gmx[dot]net>. The project is hosted on sourceforge (http://sourceforge.net/projects/bluvert). My personal blog can be found under http://wap.ecw.de (German only).

    Installation

    See INSTALL 
    		Requirements:
			* Python 2.4 or Python 2.5
			* SQLite3 bindings for Python (python-pysqlite1.1) (sudo apt-get install python-pysqlite1.1)
			* A working bluetooth environment on your machine (hcitool must be installed)
			* obexftp (sudo apt-get install obexftp)

		Installation:
			* copy all files to a directory of your choice (e.g. /usr/bin/bluvert), this is your $INSTALL_DIR
			* cd $INSTALL_DIR
			* chmod o+x execute-server.py add-message.py set-active-bluetooth-devices.sh
			* create a directory for storing your message files: mkdir /var/local/bluvert-storage, this is your $STORAGE_DIR.
			  Make sure, that $STORAGE_DIR can be written by add-message.py and read by execute-server.py! 
			* edit your $INSTALL_DIR/config.ini:
				* change "storage_dir" to your $STORAGE_DIR

		Testing (active bluetooth devices):
			* power on Bluetooth on your mobile phone and check, Bluetooth is working correctly on your machine
			* execute $INSTALL_DIR/set-active-bluetooth-devices.sh
			* cat $INSTALL_DIR/data/bt-devices.csv and be sure, your mobile phone is listed there

		Testing (adding a new message to your queue):
			* do a 'echo "Hello world" >> /tmp/bt.txt'
			* do a '$INSTALL_DIR/add-message.py -r $YOUR_MOBILE_BT_MAC -f /tmp/bt.txt -m'
			* Verify, that /tmp/bt.txt is no longer existent. 
			* Verify, that $STORAGE_DIR has a new file called 1.bt.txt

		Testing (executing the daemon):
			* execute $INSTALL_DIR/execute-server.py
			* check the output for failures
			* you should now receive the file 1.bt.txt on your mobile phone

		Setting the cron job / scheduled task:
			* Your execute-server.py should be executed every five minutes. 
			  Make sure, that $INSTALL_DIR/set-active-bluetooth-devices.sh is executed *before* $INSTALL_DIR/execute-server.py is called.
			  You need up-to-date information about active Bluetooth devices!

		More configuration options:
		$INSTALL_DIR/config.ini includes only a few options:
			* [sql.file]: Path to your SQLite3 database. I see no reason, why it should be changed
			* [data.current_bluetooth_devices]: Path to comma seperated file with active BT devices
			* [data.storage_dir]: Your storage directory
			* [exec.send_command]: This command is executed if an active BT device has outstanding messages. 
			  "$mac" will be internally replaced by target MAC address.
			  "$path_to_file" is the absolute path to the file which has to be sent

		Usage:
		execute-server.py:
			* There are no options. All options are taken from $INSTALL_DIR/config.ini

		add-message.py:
			* -r|--recipient (required): MAC address of BT device. If you use "*", the message is send to any device
			* -f|--file  (required): File which has to be sent
			* -e|--expires (optional): This parameter sets a timelimit for sending files in seconds. After this timeout, the message is discarded. 
			  Default is "0" - no timeout.
			* -m|--move (optional): The file will be moved, instead of being copied. Default is copying mode.

		Examples:
			* ./add-message.py -r * -f /tmp/welcome.wav
			  Will send the audio file welcome.wav (-f) to any BT device in your neighbourhood. 
			  There is no timeout, so this file is send to any BT device exactly one time. 
			* ./add-message.py -r 00:11:22:33:44:55 -f /tmp/backup-finished.txt
			  Will send the text file backup-finished.txt exactly one time to BT adapter 00:11:22:33:44:55
			* ./add-message.py -r 00:11:22:33:44:55 -f /tmp/backup-finished.txt -m
			  Same as before, but /tmp/backup-finished.txt will be no longer exists.
			* ./add-message.py -r 00:11:22:33:44:55 -f /tmp/pic-of-the-day.jpg -e 86400
			  Will send the JPEG pic-of-the-day.jpg to BT adapter 00:11:22:33:44:55. After 86400 seconds (24 hours) this message is discarded