EPIC data using RESTful Python


#1

For the release of the new REST API for groov Manage I have built up a couple of simple Python scripts to communicate with an EPIC processor, specifically reading and writing digital points.

The script readModCh_REST.py takes arguments for module number and channel number then returns the digitial value at that point.
The end of the script shows one way you can use Python string manipulation to make the response more human-friendly by searching for the “state” in the response text and grabbing the characters after that but before the next comma, which will only include ‘true’ or ‘false’.

## python readModCh_REST.py <mod#> <ch#>
import sys          # to handle argument values
import requests     # to make get/post requests
# ignore insecure https requests warning:
from requests.packages.urllib3.exceptions import InsecureRequestWarning
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)
# head is a JSON object that holds API key information
head = {    'apiKey' : 'SECRET_API_KEY',
            'Content-Type' : 'application/json' }
host = 'localhost'
mod = sys.argv[1] # 1st argument = module number
chn = sys.argv[2] # 2nd argument = channel number
# construct request URL for the 'local' built-in rack of I/O *status*
url = 'https://'+host+'/manage/api/v1/io/local/modules/'+mod+'/channels/'+chn+'/digital/status'
# make the RESTful get request and save the response
response = requests.get(url, headers=head, verify=False)
# if the request failed, alert the user and exit the script
if response.status_code != 200:
    print('Read request failed.')
    sys.exit()
# otherwise find the state result in the response text, then output it
else:
    start = response.text.index('state') + 7 # offset 7 letters `state:_`
    end = response.text.index(',', start)    # after the state, find the next comma
    print response.text[start:end]           # slice between `state:_` and `,`

The second script, writeModChVal_REST.py takes in three arguments: module number, channel number, and also a 1 or 0 as the value to write to that digital point. It will convert the 1/0 to true/false for you on line 15.

## python writeModChVal.py <mod#> <ch#> <1|0>
import sys          # to handle argument values
import requests     # to make get/post requests
# ignore insecure https requests warning:
from requests.packages.urllib3.exceptions import InsecureRequestWarning
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)
# head is a JSON object that holds API key information
head = {    'apiKey' : 'SECRET_API_KEY',
                    'Content-Type' : 'application/json' }
host = 'localhost'
mod = sys.argv[1] # 1st argument = module number
chn = sys.argv[2] # 2nd argument = channel number
# 3rd argument = convert value to be written from 1/0 to true/false
val = 'true' if(sys.argv[3] == '1') else 'false'
# construct request URL for the 'local' built-in rack of I/O *state*
url = 'https://'+host+'/manage/api/v1/io/local/modules/'+mod+'/channels/'+chn+'/digital/state'
# data is a JSON object that formats the value for the request
payload = '{"value":' + val + '}';
print 'Writing ' + payload + ' to output ' + chn + ' on module ' + mod
# make the RESTful put request and save the response
response = requests.put(url, data=payload, headers=head, verify=False)
# use the response code to determine if the write worked or not
if response.status_code == 200: print 'Write success!'
else: print 'Write request failed.'

Note: for both scripts you should replace SECRET_API_KEY with your actual API Key from groov Manage → Accounts.
Also replace host = 'localhost' with your controller’s hostname or IP address if you’re not running it through SSH.

The URL is constructed by using the argument values passed in to build up a string using the new REST API reference, and the use of the API is covered in more detail in the groov Manage REST API developer pages.

Here’s a screenshot of them in action:

Happy coding!


Groov EPIC-PR1 - Restful API
#2

If you want to run these on your groov EPIC with SSH access then you’ll need to get the requests library before you run the scripts, but to get that you’ll need pip, which you can get by:

  1. run update (not upgrade): sudo apt-get update
  2. then install pip: sudo apt-get install python-pip
  3. and finally the requests library: sudo pip install requests

As well as avoiding the system upgrade also do not upgrade pip itself to the latest package. Even though it may say it’s out of date, upgrading will break it but the current version works just fine.