Communication Module API¶

The AirPhoton communication module is a remote access point for AirPhoton instrumentation. It connects periodically to the /remote endpoint on the production API server.

Warning

As of October 2019, one communication module links up with one instrument.

Currently, there is developments planned for a setup with one communication module for multiple instruments.

Communication modules have two interfaces. A local USB terminal for hard configuration, and the remote interface for remote control. The following documentations will focus on remote control of the communication module as this is the interface used via the API server.

Remote Interface Overview¶

When working with the communication module through the API server, the following commands are exposed for remote operation:

echo
sendcommand
sendmlcommand
setinterval
downloadfile
transmitfile
execscript

These commands will be explained in enough detail to get started in the sections below. For more advance examples and usage cases, see the instrument specific documentation. Those sections will cover not just the instrument commands, but also some example playbook scenarios.

Note

There are more communication module commands not available over the remote interface. In addition to the commands covered here, the local USB terminal provides the following functionality:

load
save
sethost
setapipass
setnetpass
setssid
setuid

To learn more about these commands specific to site setup and the local USB terminal, in general, please see the user manual for the AirPhoton Commmunication Module.

Remote Command: `echo`¶

If you worked through the Example: Sending a Basic Command in API Server, you already sent an echo command via a communication module to an instrument. We can use echo to check connectivity with the communication module in the same way.

Note

Under normal setups, a communication module will not connect to the API server unless there are instruments attached and powered.

If you can echo an instrument remotely, you know the communication module is also working. Therefore, sending echo to the communication module is likely not needed, but it can be handy diagnostic tool.

We want to create a control action with the command echo online. If you examine the JSON closely, you will notice that an instrument reference is required since the communication module will not connect to the API server alone.

# NOTE:
# This command has the [INSTRUMENT-URL] and [USER-URL] pre-populated.
# Make sure you change these.
curl --user [USER] \
--request POST https://sandbox.airphoton.io/v1/controls/ \
-H "Content-Type: application/json" \
-d '{"instrument":"https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/","created_by":"https://sandbox.airphoton.io/v1/users/3/","name":"api demo","command":"echo online"}'

After sending the command, monitor the controls UUID provided. Once the status field is completed, check the controlresponse associated with that UUID to make sure the communication module responded as expected. Your output will vary slightly, but it should look similar to the following:

[{
    "url": "https://sandbox.airphoton.io/v1/controlresponses/f77aa3e5-5a47-4466-a15d-a4651ca8b827/",
    "control": "https://sandbox.airphoton.io/v1/controls/7875b454-d18f-4268-9930-1ec012081cc8/",
    "error": "",
    "response": {
        "text":"echo online\r\n"
    }
}]

Compared to the example in controlresponses Functionality which was sent to the instrument, the text output is only echo online when the communication module alone responds.

Remote Command: `setinterval`¶

The communication module checks in with the API server at set time intervals whenever an instrument is attached and powered. When used remotely, the setinterval command can be used to report and to temporarily change this check-in interval.

Warning

The check-in interval affects bandwidth. When operating on a metered Internet connection this can drive up costs or lock out the cellular module account.

The setinterval time should be as slow or as large as reasonably usable. This command exists to temporary change the setinterval when remote user interaction is needed, and slow responses are not tolerated.

If you reduced the setinterval, remember to return it to the original setting.

AirPhoton recommends [TBD] interval as a default.

Reporting the `setinterval`¶

The setinterval period can be requested remotely by sending the command without a value. Notice that in the following example, the command sent is only setinterval.

# NOTE:
# This command has the [INSTRUMENT-URL] and [USER-URL] pre-populated.
# Make sure you change these.
curl --user [USER] \
--request POST https://sandbox.airphoton.io/v1/controls/ \
-H "Content-Type: application/json" \
-d '{"instrument":"https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/","created_by":"https://sandbox.airphoton.io/v1/users/3/","name":"api demo","command":"setinterval"}'

After sending the command, monitor the controls UUID provided. Once the status field is completed, check the controlresponse associated with that UUID to see the current setinterval period. Your output will vary slightly, but it should look similar to the following:

[{
    "url": "https://sandbox.airphoton.io/v1/controlresponses/42f034af-f6c4-4e28-be31-9e5ac7d7a7ff/",
    "control":"https://sandbox.airphoton.io/v1/controls/5bbfb7f6-0e92-4c36-8cab-4f6d26fec162/",
    "error":"",
    "response": {
        "text":"Interval is:300\r\n"
    }
}]

Changing the `setinterval`¶

Warning

When used remotely, the setinterval command will not persisted in storage. When the system is rebooted such as during a power loss event, it will reboot using the stored setting.

To persist setinterval changes, use the command while connected to the local USB terminal. For more information, please see the user manual for the AirPhoton Communication Module.

The setinterval period can be changed remotely by sending the command with the new period in seconds. Notice that in the following example, the command sent is setinterval 60.

# NOTE:
# This command has the [INSTRUMENT-URL] and [USER-URL] pre-populated.
# Make sure you change these.
curl --user [USER] \
--request POST https://sandbox.airphoton.io/v1/controls/ \
-H "Content-Type: application/json" \
-d '{"instrument":"https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/","created_by":"https://sandbox.airphoton.io/v1/users/3/","name":"api demo","command":"setinterval 60"}'

After sending the command, the communication module should start checking in with the API server at the new rate.

Remote Command: `sendcommand`¶

This command asks the communication module to send a command to the instrument and report back the results.

The example in Example: Sending a Basic Command from API Server covers the same principle of setting up a JSON object to send.

We will create another control action with the command sendcommand. The communication module will take the parameters given after sendcommand and send that to the instrument, returning the result.

We will use the same example command given: sendcommand echo Science!

# NOTE:
# This command has the [INSTRUMENT-URL] and [USER-URL] pre-populated.
# Make sure you change these.
curl --user [USER] \
--request POST https://sandbox.airphoton.io/v1/controls/ \
-H "Content-Type: application/json" \
-d '{"instrument":"https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/","created_by":"https://sandbox.airphoton.io/v1/users/3/","name":"api demo","command":"sendcommand echo Science!"}'

In this case, the instrument should respond back similarly to the following:

[{

    "url": "https://sandbox.airphoton.io/v1/controlresponses/8d0c99a1-0dbb-48d0-863c-b9e48d326183/",
    "control": "https://sandbox.airphoton.io/v1/controls/7df9437a-d7cb-468f-a957-79d114dfd9ba/",
    "error": "",
    "response": {
        "text": "Instrument:echo Science!\r\n"
    }
}]

Remote Command: `sendmlcommand`¶

This command is very similar to sendcommand, but is used for multiline responses from the instrument.

In this example, we will ask the communication module to get the status of the instrument using sendmlcommand ENDSTATUS status.

# NOTE:
# This command has the [INSTRUMENT-URL] and [USER-URL] pre-populated.
# Make sure you change these.
curl --user [USER] \
--request POST https://sandbox.airphoton.io/v1/controls/ \
-H "Content-Type: application/json" \
-d '{"instrument":"https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/","created_by":"https://sandbox.airphoton.io/v1/users/3/","name":"api demo","command":"sendmlcommand ENDSTATUS status"}'

You should expect the response to be similar to sendcommand, but with a much larger text field in response:

[{
    "id": "66be44f8-23d2-4953-a0f2-77658402dccf",
    "control": "https://sandbox.airphoton.io/v1/controls/937e2977-e049-4383-b49f-0f29072f40d9/",
    "error": "",
    "response": {
        "text": "Instrument:serialnumber=SS5013\r\ndate=2020-02-06\r\ntime=13:00:18\r\nmemoryfree=76572\r\nmode=script\r\nrtcbattery=ok\r\ncartridge=275\r\ncartridgecount=255\r\nscriptcartridge=-1\r\nstorage=backup,cartridge\r\nscriptname=script.aps\r\nscriptstate=not_running\r\nscripterror=none\r\nscriptline=none\r\nactivefilter=none\r\ndataname=\r\npump_a=off\r\npump_b=off\r\nflow_a=0.01\r\nflow_b=0.03\r\nvacuum_a=0.04\r\nvacuum_b=0.51\r\ntemperature=28.96\r\n\r\n"
    }
}]

The response is lengthly and contains unescaped line-endings, so here is the response formated as an unescaped

Instrument:
serialnumber=SS5013
date=2020-02-06
time=13:00:18
memoryfree=76572
mode=script
rtcbattery=ok
cartridge=275
cartridgecount=255
scriptcartridge=-1
storage=backup,cartridge
scriptname=script.aps
scriptstate=not_running
scripterror=none
scriptline=none
activefilter=none
dataname=
pump_a=off
pump_b=off
flow_a=0.01
flow_b=0.03
vacuum_a=0.04
vacuum_b=0.51
temperature=28.96

Remote Command: `downloadfile`¶

Remote files are not downloaded directly to an instrument. They are first buffered by the communication module using the downloadfile control. After the download is complete, see the transmitfile control in the next section below.

The following command schedule a control action with the central server. The specific command to be sent to the communication module is downloadfile [URL] /[NAME]. The file URL can be any HTTPS source backed by a Lets Encrypt Certificate.

Here are some example scripts provided by AirPhoton for testing:

curl --user [USER] \
--request POST https://sandbox.airphoton.io/v1/controls/ \
-H "Content-Type: application/json" \
-d '{"instrument":"https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/","created_by":"https://sandbox.airphoton.io/v1/users/3/","name":"script download","command":"downloadfile https://www.airphoton.io/_downloads/d9f683385e77db0c392924ed251a01e2/simple-eight.aps /script.aps"}'

In this case, the instrument should respond back similarly to the following:

[{
    "url": "https://sandbox.airphoton.io/v1/controlresponses/33390f84-5dfd-4482-acd7-550e642065f1/",
    "control": "https://sandbox.airphoton.io/v1/controls/ed853a9d-5e7e-4563-8116-ce46d2f8f19e/",
    "error": "",
    "response": {
        "text":"downloading file succeeded\r\n"
    }
}]

Remote Command: `transmitfile`¶

transmitfile takes two positional arguments: transmitfile [source] [target]

This command will copy the contents of the source file downloaded from downloadfile into a new file located at [target] on the instrument. The target location must be rooted at either B (BACKUP) or C (CARTRIDGE). Omitting this indicator will default to B.

For example, after creating the example control action above for downloadfile, transmitting that file using transmitfile /script.aps script1.aps:

curl --user [USER] \
--request POST https://sandbox.airphoton.io/v1/controls/ \
-H "Content-Type: application/json" \
-d '{"instrument":"https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/","created_by":"https://sandbox.airphoton.io/v1/users/3/","name":"script transmit","command":"transmitfile /script.aps script.aps"}'

Remote Command: `execscript`¶

execscript takes up to two positional arguments: execscript (strict) [source]

Execute a script with optional strict mode.

Communication Module API¶

Remote Interface Overview¶

Remote Command: echo¶

Remote Command: setinterval¶

Reporting the setinterval¶

Changing the setinterval¶

Remote Command: sendcommand¶

Remote Command: sendmlcommand¶

Remote Command: downloadfile¶

Remote Command: transmitfile¶

Remote Command: execscript¶

Remote Command: `echo`¶

Remote Command: `setinterval`¶

Reporting the `setinterval`¶

Changing the `setinterval`¶

Remote Command: `sendcommand`¶

Remote Command: `sendmlcommand`¶

Remote Command: `downloadfile`¶

Remote Command: `transmitfile`¶

Remote Command: `execscript`¶