Specification of device user interface, or dui

Users can use a device to communicate with the iGPIO web site via the dui; to do this, the device must be programmed in order to communicate with the iGPIO web site. In this page, we will provide the necessary information in order to use the dui. The sample code is all in python, but the interface is not limited to python.

The method used for a request-response between a client (i.e., the device) and server (i.e., iGPIO) is POST. Since sensitive information may be included in the communication, it is strongly recommended to use https instead of http. The request POST data structure is as follows:

• url = 'https://www.igpio.net/scripts/dui.php' #This specifies the URL of the iGPIO page for the dui
• query_args = {'u':uid,'p':pw,'d':device,'t':'TS', 'r':rstr,'w':wstr,'m':mstr,'s':sstr} # query_args is the string to be sent to the iGPIO web site
• data = urllib.urlencode(query_args) # data is the encoded version of query_args
• request = urllib2.request(url, data) # request is the data that is POST to the web site.
• response = urllib2.urlopen(request).read() # response is what the web site sends back to the device
  

Note: Users need to set query_args correctly. We use an example to explain all the parameters:

query_args = {'u':'me@my_company.com','p':'safe_code','d':1,'t':'TS','r':'1;2@=0','w':'3@=3.14;4@=1.23','m':'my message','s':'my subject'}

parameter 'u' is the user ID, me@my_company.com; it is an email address which a user has registered at iGPIO. If you have not registered, you can click on this link to register.

Parameter 'p' is the password, safe_code, that you chose when you registered at iGPIO

Both user ID and password are required. If these two strings are not set correctly, iGPIO will reject your request.

Parameter 'd' is the device number. If you have only one device, set it to 1. If you don't set this parameter, the default is 1.

Parameter 't' is optional. If you set this parameter, iGPIO will send you a time stamp, led by the string you entered, in this case TS, e.g.:

TS1420576594.

Parameter 'r' is a list of channels that you want to read/update from iGPIO. All enabled channels can be read regardless of the iGPIO flag setting. Channels with flag set to 1 can be both read and updated. In this example, the flag on channel 2 is set to 1. The @ is optional in a read request; if it is there it can be used to set the channel to a specific value as in this example.

 iGPIO will return the following information for each channel in a read request:

Chn,Value,Value 2,Value 3,Label,Flag

e.g., for channel 1

CH1,2.000,0.000,0.000,my_label,0

and for channel 2

CH2,5.000,0.000,0.000,my_label2,1

Please note that for this example, on iGPIO the value 5.000 (Value) in channel 2 will be set (changed) to 0.000. The response from iGPIO for this reading will be

READ_RESULT:
CH1,2.000,0.000,0.000,my_label,0
CH2,5.000,0.000,0.000,my_label2,1
CH2,Info,my_label2,0,updated
END_READ_RESULT

Parameter 'w' is a list of channels that you want to update at iGPIO. Channels with flag set to 0 can be updated. In this example, the flags on channel 3 and 4 are set to 0. The @ is required for all write requests and is used to set a specific value for a given channel.

iGPIO will return the following information for each channel in a write request:

WRITE_RESULT:
CH3,Info,my_label3,3.14,updated
CH4,Info,my_label4,1.23,updated
END_WRITE_RESULT

Parameters 'm' and 's' are the device email information, m is for the message body and s is for subject. When either one is set, an email will be sent to the user. However, if two email requests are made separated in time by less than D Mail Interval, e.g., 3600s (one hour) setting at iGPIO (Device Manager) for the given device, the second email request will be rejected by iGPIO.

Key words (lines end with charactor '\n')

REQUEST_STATUS

In the response from iGPIO, there will be a line REQUEST_STATUS=1 to indicate that the request was accepted, or a line REQUEST_STATUS=0 to indicate that the request was rejected, which can happen when the time separation of two requests is less than the Update Interval, e.g., 300s setting at iGPIO (Device Manager).

BUI_UPDATE

A line BUI_UPDATE=1 indicates that at least one parameter has been changed via the browser user interface (BUI) since the most recent prior device access. It will be set to BUI_UPDATE=0 after a read request made by a device.

READ_RESULT:
...
END_READ_RESULT

The entire response related to the read request is placed within the READ_RESULT:, END_READ_RESULT lines.

WRITE_RESULT:
...
END_WRITE_RESULT

The entire response related to the write request is placed within the
WRITE_RESULT:, END_WRITE_RESULT lines.

EMAIL_STATUS

In the response from iGPIO, there may be a line EMAIL_STATUS=1 to indicate that the device email has been sent, or a line EMAIL_STATUS=0 to indicate that the device email has not been sent, which can happen when the time separation of email requests is smaller than the D Mail Interval, e.g., 3600s (one hour) setting at iGPIO (Device Manager).

TOKEN_STATUS

A line TOKEN_STATUS=n,k indicates that there are n tokens remaining for this device, and k tokens have been used for the current query. Tokens can be used to override the interval limits defined by 'Update Interval' and 'D Mail Interval'. The 'Update Interval' limit will be overridden automatically (cost one token) if the device has any tokens remaining at the time of the request. To override 'D Mail Interval' limit (cost one token), it is necessary to include the string 'urgent' in either of the parameters 'm' or 's'.