MessageSend
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 127.0.0.1, localhost, ::1, ip6-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
-
- none
- direct_siblings
- same_computer
- same_room
- same_house*
- all_houses
*needs valid device ID for this to be useful
-retry
means what to do if the message cannot be delivered;
- values
-
- none (don't retry)
- retry (send it when the device registers)
- 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
Also see Virtual Device List
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
Detailed 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:
Samples with MessageSend
Here are some sample messages you can send with the MessageSend utility.
Detection Commands
- Detected a new device on the network
/usr/pluto/bin/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
/usr/pluto/bin/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
/usr/pluto/bin/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
/usr/pluto/bin/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
/usr/pluto/bin/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
- Event "Now Playing"
/usr/pluto/bin/MessageSend dcerouter 271 -1001 2 58 4 "Text to be displayed for Orbiter variable %NP%"
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"
Query Commands
- Device states and data can be queried using MessageSend. We will send messages to the General_Info_Plug-in (device #4) which will respond with the device data we are looking for. The "-o" parameter tells MessageSend we are expecting output data and to pass it on to us.
To query the state of a device, like a light switch or dimmer send command #247 "Get Device State". The ID is the device number that you wish to know the state of.
/usr/pluto/bin/MessageSend localhost -o 0 4 1 247 2 ID
This will result in a response similar to the following: ON, dimmer or switch turned "ON"
0:OK 5:ON/255
ON, dimmer set to 70% brightness
0:OK 5:ON/70
OFF, dimmer previously set to 70% but currently turned "OFF"
0:OK 5:OFF/70
- Query data from a device. We send command #68 "Get Device Data". Parameter 2 selects the device to get data from, in this case data is being requested from device #13 the Security_Plug-in. Parameter 52 selects the data field to retrieve, in this case we are looking for device data field #59 "Configuration" (which stores the default house mode in this case). Parameter 53 selects whether "live" or "default" data is retrieved, 0=live, 1=default.
/usr/pluto/bin/MessageSend localhost -o 0 4 1 68 2 13 52 59 53 1
Response:
0:OK 5:0,2,
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. Have no clue on meaning of parameters for buttons - anyone knows?
/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 ?
Yes, the Orbiter PlugIn provides Display Dialog Box, which can be used from MessageSend as follows:
/usr/pluto/bin/MessageSend localhost 0 9 1 686 9 "Dialog Box Text" 39 "message1|button text 1|message2|button text 2|message 3|button text 3|message4|button text 4" 103 ""
0 of course, coming from MessageSend 9 is the Orbiter PlugIn, this can be replaced with the virtual device for the Orbiter PlugIn
Dialog Box text can be anything, \n is parsed as well. message1 is the message to send when button text 1 is clicke button text 1 is of course, the text to show for the button. repeat for up to 4 buttons.
This will display a dialog box on all orbiters with the text "Test String" and 2 option buttons: "Message1" and "Message2". I'm not sure how to tell which option is selected after that. After clicking one of the option buttons, I can see that the orbiter sends a bind to media remote command to the media plugin, though I'm not sure why.
/usr/pluto/bin/MessageSend dcerouter -r 0 9 1 686 103 "" 39 "option1|messag1|option2|message2" 9 "Test String"
