Difference between revisions of "MessageSend"

Revision as of 16:22, 4 September 2008

Command

MessageSend server [-targetType [device|category|template]] [-r | -o] [-p path] [-bl BroadcastLevel] [-retry value] DeviceFrom DeviceTo MsgType(1=Command, 2=Event) MsgID [parm1id param1value] [parm2id parm2value] ...

Parameters

This are derived from the help text of the above command, Please add any additional information that will be useful for helping understand this very important command.

server

is the name/ip of the router, such as localhost or dcerouter

targetType

the default target type is the device, category, or template

-r

means the message will be sent with a response request

-o

means the message will expect out parameters which will be echoed to the screen as resp: [response]

-p

specifies the path for output parameters

-bl

means the broadcast level if the message is sent to category or template;

values 

1. none
2. direct_siblings
3. same_computer
4. same_room
5. same_house*
6. all_houses

*needs valid device ID for this to be useful

-retry

means what to do if the message cannot be delivered;

values

1. none (don't retry)
2. retry (send it when the device registers)
3. persist (retry, but survive a reload router)

DeviceFrom

Device number the messages is coming from.

DeviceTo

Device number the message is going to'

MsgType

    1= Command
    2= Event

MsgID

format is as follows: MsgID [parm1id param1value] [parm2id parm2value] ...

         the parm ID can be prefixed with a letter:
               D send as a data parameter, rather than text
               U send as a data parameter, rather than text, parameter is UU-encoded
               B the value is a filename, the contents sent as a data parameter
               T the value is a filename, the contents sent as a text parameter

Alternatively: MessageSend uuencode file_in [file_out] (writes to stdout no file_out) or MessageSend uudecode file_out [uuencodeddata | file_in]

System Devices Hard Coded

from src/DCE/Message.h

// Some system devices
30 	#define DEVICEID_DCEROUTER      -1000   // System commands for the router itself
31 	#define DEVICEID_EVENTMANAGER   -1001   // Not a real device, just the destination of events
32 	#define DEVICEID_LOGGER                 -1002
33 	#define DEVICEID_MESSAGESEND    -1003   // The message send utility
34 	
35 	// Virtual devices
36 	#define DEVICEID_MASTERDEVICE   -2000
37 	#define DEVICEID_CATEGORY       -2001
38 	#define DEVICEID_LIST           -2002
39 	#define DEVICEID_GROUP          -2003
40 	
41 	// Other
42 	#define DEVICEID_HANDLED_INTERNALLY -300

Detailed Breakdown of MessageSend for a Command

   /usr/pluto/bin/MessageSend localhost 0 13 1 19 5 6 17 7 99 5678 100 0 101 R

Parameters in this command line are :

   localhost server
   0 DeviceFrom
   13 DeviceTo (Security plugin)
   1 MsgType: Command
   19-Command "Set house mode"
   The rest are MsgID blocks which require [parmid paramvalue]
   parmid 5(Value To Assign): paramvalue 6
   parmid 17(PK_Users): paramvalue 7
   parmid 99(Password): paramvalue 5678
   parmid 100(PK_DeviceGroup): paramvalue 0
   parmid 101(Handling Instructions): paramvalue R

Additional Commands on the LinuxMCE Admin Website under Advance|DCE|Commands Open a command to see valid parameters available for each command

Detailed Breakdown of MessageSend for an Event

Tripping security sensor with ID of 195 to ON :

   /usr/pluto/bin/MessageSend dcerouter 195 -1000 2 9 25 1

Parameters in this command line are :

   dcerouter server
   195 DeviceFrom
   -1000 DeviceTo (DCERouter)
   2 MsgType: Event
   9 Event "Sensor Tripped"
   The rest are MsgID blocks which require [parmid paramvalue]
   paramid 25(Tripped) : 1 

Additional Events on the LinuxMCE Admin Website under Advance|DCE|Events Open a event to see valid parameters available for each event

Detaild Breakdown of MessageSend to Display Alert on Orbiters

/usr/pluto/bin/MessageSend dcerouter -targetType category -bl 5 1 5 1 809 251 0 9 "TESTING DISPLAY ALERT" 182 15 70 "test"

Parameters in this command line are :

   dcerouter server
   category targetType(device category found on template page)
   5 -bl broadcast level 5 or whole house
   1 DeviceFrom (Core)
   5 DeviceCategory (actually device category 5 orbiters)
   1 MsgType: Command
   809 Command "DISPLAY ALERT"
   The rest are MsgID blocks which require [parmid paramvalue]
   251 (Interruption : 0
   9 (Text) : "TESTING DISPLAY ALERT"
   182 (Timeout) : 15 seconds
   70 (Tokens) : "test"

For additional information regarding the MessageSend command take a look at the following pages:

• DCE from commandline
• Sensors

Samples with MessageSend

Here are some sample messages you can send with the MessageSend utility.

Detection Commands

• Detected a new device on the network

   ./MessageSend dcerouter $PK_Device -1001 2 65 28 "192.168.80.99" 5 "00:10:75:00:D2:22" 52 3 53 2

• and when the device is no longer on the network

   ./MessageSend dcerouter $PK_Device -1001 2 66 28 "192.168.80.99" 5 "00:10:75:00:D2:22" 52 3 53 2

• A USB device is detected

   ./MessageSend dcerouter $PK_Device -1001 2 65 55 "37|usb2/2-2/2-2:1.7" 52 4 51 "0403f850"

Note that the vendor/model id is specified, which will be looked up in the DHCP Device database. And parameter 55 is specified so that when the device is created it will have a device data 37 (com port on pc) of "usb2/2-2/2-2:1.7". The usb detection device should automatically determine that the device connected appears as a usb com port, and therefore pass in that com port as a parameter to the event.

• Some RS232 device is detected, probably because a generic USB->RS232 dongle was attached

   ./MessageSend dcerouter $PK_Device -1001 2 65 55 "37|usb2/2-2/2-2:1.8" 52 2

Note the comm method is RS232, and the port "usb2/2-2/2-2:1.8" is specified. The plugin will run every detection script in DHCPDevice for all RS232 devices until one detection script reports a match.

• An internal hard drive is detected

   ./MessageSend dcerouter $PK_Device -1001 2 65 55 "152|/dev/hdb1" 52 8 49 1790

• The detection script should attempt to determine what device template is on the path using any appropriate means. If it finds a match, it should fire a message using the paramters it received, such as this:

   /usr/pluto/bin/MessageSend dcerouter -r 0 $1 806 224 $2 13 "$4" 44 1752

which means the device is template 1752.

• If the device template is not something that it can determine, send the message leaving off parameter 44 (ie leave off the 44 1752). If there is some error condition you want logged, add parameter 18, as this:

   /usr/pluto/bin/MessageSend localhost -r 0 $1 806 224 $2 13 "$4" 18 "the com port doesn't exist" 

• For a NAS this comes from dhcp monitor and has the ip/mac and plug and play plugin figures out what it is, like this:

   /usr/pluto/bin/MessageSend dcerouter 0 -1001 2 65 52 3 53 2 5 "00:0D:0B:99:10:43" 28 "192.168.80.7"

• For the “scan the network for windows shares” utility that always runs in the background, it explicitly sends a device detected event with the device template Generic File Server 1837, like this:

   /usr/pluto/bin/MessageSend dcerouter 0 -1001 2 65 52 3 53 2 49 1837 

• Once the device is created, the configure script will be ran, for example: Configure_1794.sh for the Buffalo Terastation. This script should lookup the username and password for the device from the database and fire a 'device detected' for each network share, as follows:

   /usr/pluto/bin/MessageSend dcerouter X -1001 2 65 52 3 53 2 49 1768 55 "182|1"

That that the X must be the device number of the fileserver, since the file share will be a child of that. 1768 is the template for a samba share, 1769 for nfs. If the share does not require a password, leave off the 55 "182|1". If the username and password already specified in the database are valid for the share, then instead of 55 "182|1" do 55 "127|username|128|password".

Events

• Tripping security sensor with ID of 195 to ON :

   /usr/pluto/bin/MessageSend dcerouter 195 -1000 2 9 25 1

• Tripping security sensor with ID of 195 to OFF :

   /usr/pluto/bin/MessageSend dcerouter 195 -1000 2 9 25 0

• Report that light with ID of 210 is ON :

   /usr/pluto/bin/MessageSend dcerouter 210 -1000 2 48 10 1

• Report that light with ID of 210 is OFF :

   /usr/pluto/bin/MessageSend dcerouter 210 -1000 2 48 10 0

• Send a new temperature to thermastat with ID of 121

   /usr/pluto/bin/MessageSend dcerouter 121 -1000 2 25 30 temperature_value

replace temperature_value with a actual temperature in degrees

• Event "output on"

   /usr/pluto/bin/MessageSend dcerouter ID  -1000 2 28

• Event "output off"

   /usr/pluto/bin/MessageSend dcerouter ID  -1000 2 29

Sending Commands

• Play media (/home/public/data/tts/0.wav) on Xine player with ID of 44 :

   /usr/pluto/bin/MessageSend localhost 0 44 1 37 29 "" 41 "" 42 "" 59 "/home/public/data/tts/0.wav"

• Execute scenario with PK_CommandGroup = 157 from device with ID :

   /usr/pluto/bin/MessageSend localhost ID -1000 1 370 28 "157"

Other messages

Work in Progress

Will parse the meaning of DCE messages below in future. Just wrote it here to remember....

• It seems like "Goto Screen" command for Popup screen (It switches Orbiter #64 to screen with "A message" and two buttons ("Ok" and "Remind me later") with separate actions for each one

   /usr/pluto/bin/MessageSend localhost 0 64 1 741 10 "Whatever" 159 53 9 'A message|Ok|Remind me later' 137 '-targetType device <%=!%> 15 1 67 13 "/root/Something.sh" 51 "--answer yes"|-targetType device <%=!%> 15 1 67 13 "/root/Something.sh" 51 "--answer no"'

• To display Text Alert on Orbiter :

   /usr/pluto/bin/MessageSend localhost 0 20 1 809 9 "Text to Display" 70 "alert" 182 "30" 251 "??"

Also interesting command is #397 "Show popup", but I have yet to discover how to use it...

Does anyone know how to display popup with question and few answer buttons (yes/no for example) ? Can this be done without Designer to create screen - just to specify question, texts on buttons and actions on click ?

Additional Resources

• Message Interceptors