ControlMyPi docs

Widgets

The widget definition generally follows the pattern Type, Name, Value. For example the following is a definition of a button called "my button" which has the text "Press me!" on it:

Button:

['B','my button','Press me!']

When pressed this will call on_control_message on your Pi with 'my button' as the key and True as the value.

Entry box:

['E','echobox','send']

When the button is pressed on_control_message is called with 'echobox' as the key and the content of the entry box as the value.

Status text:

['S','echostatus','Initial status']

Initial status

If you want to update the status text from your Pi to say "Hello world" you would write this:

conn.update_status({'echostatus':'Hello world'})

Picture:

['P','my_pic','http://maps.googleapis.com/maps/api/streetview?size=260x200&location=40.72,-73.98&sensor=false']

If you want to update the picture:

conn.update_status({'my_pic':'http://maps.googleapis.com/maps/api/streetview?size=260x200&location=40.82,-73.88&sensor=false'})

Gauge:

['G','speed','mph',20,0,50]

In this example speed is the Name of the widget, mph is the label to appear on the gauge, 20 is the current speed, 0 is the minimum speed and 50 is the maximum. If you want to update the gauge:

conn.update_status({'speed':25})

Colour wheel:

['W','wheel']

This widget sends a hex code of the colour choice to your Pi. E.g. #FF0000 with, in this case, wheel as the key.

Colour indicator:

['I','indicator','#FFF000']

If you want to update the colour send it a hex code:

conn.update_status({'indicator':'#00FF00'})

Line chart:

['LC','speedchart','time','mph',0,40]

The line chart is typically used to show a value changing over time. In the example speedchart is the Name for this widget, time is the x axis and mph the y axis. To specify a fixed range for the y axis enter the min and max values, 0 and 40 in this example. If you omit the min and max the y axis will adjust automatically to fit the range of values in the data. Line charts are blank when initialised (as shown here) - you must send data through an update to display your line:

conn.update_status({'speedchart':[ [1,50], [2,50.1], [3,50.2] ]})

Note: all the data points are supplied in the update. If you want to have a rolling chart (new data points on the right push the oldest data point off the left) then a simple function like below is very useful. This will maintain 10 points on the chart:

schart = []

def append_chart_point(chart, point):
    if len(chart) >= 10:
        chart = chart[1:]
    chart.append(point)
    return chart
    
schart = append_chart_point(schart, [t,spd])

conn.update_status({'speedchart':schart})
	

Label:

['L','Enter message:']

Enter message:

Layout

The panel layout is defined in rows. Each List defines a new row:

panel_form = [
	[ ['L','First row'] ],
	[ ['L','Second row'] ]
]

First row
Second row

Grid:

When defining a button panel for example you may want to arrange the widgets in a grid so they line up neatly. You can open and close grids using the 'O' and 'C' widgets:

panel_form = [
	[ ['O'] ],
	[ ['L','GPIO 4'],['B','4on','on'],['B','4off','off'],['S','GPIO4','on'] ],
	[ ['L','GPIO 17'],['B','17on','on'],['B','17off','off'],['S','GPIO17','off'] ],
	[ ['C'] ]
]
GPIO 4 on
GPIO 17 off

ControlMyPi class

Constructor:

conn = ControlMyPi(
	jabber_id,
	password,
	panel_id,
	panel_name,
	panel_form,
	on_control_message,
	visibility,
	on_registered)
jabber_id
Your Jabber/XMPP ID or JID (known as a bare jid) e.g. myname@gmail.com
password
Your Jabber/XMPP account password to sign in to your Jabber service (not shared with ControlMyPi!)
panel_id
A short identifier for this panel unique among all panels using this jabber_id. Must be between 1 and 9 alphanumeric characters.
panel_name
The friendly name for this panel which will appear on controlmypi.com
panel_form
The layout list defining the form. (See the Widgets and Layout sections above)
on_control_message
A method to call whenever there's an incoming message, (see below)
visibility
One of: 'pub' - available on the front-page of controlmypi.com,
'hid' - only accessible to people who know your Jabber ID,
'pri' - private (Not available yet!)
[optional - defaults to 'hid']
on_registered
A method to call when your Pi is first registered with controlmypi.com, (see below) [optional]

Recommended main loop:

if conn.start_control():
  try:
    main_loop()
  finally:
    conn.stop_control()
else:
  print("FAILED TO CONNECT")

Create a function called main_loop where you do your core processing. The Jabber connection runs in a separate thread calling your on_control_message whenever a message comes in. When you exit main_loop the connection will be closed and the program will stop. So keep a loop running in main_loop and occasionally yield with a call to sleep(). See the examples.

Receiving messages:

def on_control_message(conn, key, value):
  print key, value

Define your on_control_message function with this signature. See the Widget section above for what key/value pairs are sent through from your control panel. A reference to your ControlMyPi instance is passed in as the first parameter

Updating the control panel:

conn.update_status({'status1':'Hello','status2':'Goodbye'})

Send a dict with key/value pairs to update Widgets in your control panel. See the Widget section above to find out which Widgets you can update.