Orax SDI Cloud Reference

Automation configuration

Using Orax Automation modules, you're able to control and monitor the outside world from Orax SDI. This means that you can open doors, control timers, read physical events and more from Orax SDI. Automation module can be managed manually from smartphones and configured to operate on a timer. All this is configured on the Orax SDI portal under the Update tab of a System.

An Orax Automation module is nothing other than a small computer, connected to the internet via Wifi, ethernet or 3G, which runs an Orax Automation Agent program. These computers are monitored by the Orax SDI server just like a normal system with metrics. In addition, it has the ability to read output commands from the server (eg. open a door or switch on a pump) and send input to the server (eg. alarm trigger, low level switch).

When Automation modules are manually controlled by a smartphone (eg. open a gate), the applicable user accounts which were given access to the system will have a set of buttons on their Orax SDI homepage menu. These buttons control the Automation modules via the Orax SDI server.

The network architecture works like this. The Orax SDI server is central. All Automation modules connect to the server to upload metrics and receive commands. The remote control from smartphone or tablet connect to the Orax SDI server and issues the control request/command. All communication is secure (HTTPS / SSL) which ensures a simple and secure wide-area automation network. An Automation module is an Orax SDI system (also used in wide-area-monitoring).

To configure an Automation module or Automation remote (smartphone buttons), go to the Update tab of the Applicable system. Note that for remote buttons, one system can be used to control other systems (automation modules). The buttons are setup on a system.

Event based configuration is possible be adding a command to a metric when the metric goes bad or back good. See the bottom of this page for the configuration detail. Event based configuration is used for instance to switch on a pump when the level gets to low or high, or to switch on a fan when the temperature gets too high.

Under the "Automation configuration" section, enter your configuration in the applicable text field. Allowed users who may access the remote app can be linked in the "Automation Access" field.


ACTIVATION:

To ensure the agent listens for automation commands, setup the oraxagent.conf file with the following option:

CMD:::ON



CONFIGURATION:

Timer configuration:
TIMER:0800:[1,2,3,4,5]:[on|off]IO_Pin,s10,[on|off]IO_Pin

(TIMER:HHMM:Days of week (0 = Sunday) or blank for all days:script)

Eg. TIMER:0730:1,2:/dr1/gui/lights_on

Alternatively you can also add a "w" to the days of week section.
Eg. TIMER:0800:1,2,3,w:cmd or TIMER:1030:w:cmd
The "w" will tell the system that the command should only be executed on a "working day". If the date falls on a public holiday or weekend the command would not be executed.
Finally you may use SUNSET or SUNRISE as the time (instead of HHMM). You may also use SUNRISE+15 or SUNSET-30 to adjust by minutes (eg. sunrise plus 15 minutes).

TIMER:HHMM::run_code&Code Name[&action&key&menuflag]
(runs custom code on the server at the specific time - optionally add Parameters)


Startup States for IO Pins
IO_STATE:on1:[0900-1200]:[1,2,3,4]

To set a startup state for an IO pin, use the IO_STATE command. You can optionally include a time of day and day of week.

Eg. the following are valide options:

IO_STATE:on1:0900-1200:1,2,3,4
IO_STATE:on2:0800-1000
IO_STATE:on3


Startup Action
STARTUP_ACTION:linux command

Used to restore a more complex state after a reboot. Examples are to restore the state of a local file to correspond to the server state.




Input configuration:
INPUT=In_Pin[on|off][,MetID,MetValue]:ifIO_Pin[on|off],[on|off]IO_Pin,wIO_Pin[on|off][/seconds sleep],[on|off]IO_Pin,s(sleep seconds),[on|off]IO_Pin,rx25&15&Check it,sms0821234567,else,s(sleep seconds),rSysIDpIO_Pin[on|off],rcSysIDcmd/usr/bin/omxplayer /dr1/siren.mp3

(The above command will run local and work without any network)

INPUT=In_Pin[on|off],MetID,MetValue

(The above command will only update a metric at the time of the event. All actions will be handled globally in the metric's error handling, using AUTOMATION commands.)

NOTES:
s = Wait for X seconds.
w = Wait until input condition with maximum of X seconds.
if = Check condition of IO_Pin (ether on of off)
else = add else condition for above if statement
r = remote IO_Pin output
rc = remote OS command
sms = send SMS (optional message = sms0821234567This is the message)
rx = execute custom code # on server and pass Parameters (separated by &) - eg. rx123&action&key.
Metric is optional and is used for uploading/recording values/events/usage.


Camera configuration:
CAMERA_SYSTEM
This keyword in the System's Automation configuration will cause the System to act like a surveillance camera.

ON_CAMERA_BUTTONS
This keyword in the System's Automation configuration will prevent the system from showing on the homepage and allow for on system buttons as defined below. This enables you to watch the camera image while having buttons available on the same page so you can control doors and gates while watching.

CAMERA_SHOW=SystemID
When added to a button configuration it shows the latest camera image of SystemID on the button screen. When you tap the image it goes to the actual camera. It is required that the user have access to the camera as defined in the automation configuration for the camera system.

ECHO_TOGGLE=219:1:1:197:echo 8000 > /dr1/agent/cam_motion
ECHO_TOGGLE=219:1:0:197:rm -f /dr1/agent/cam_motion
The above commands enables and disables motion detection for a camera when another system is switched. This is typically for alarm activation and deactivation. Notice the 8000 in the first command. It configures motion detection threshold for the camera. The default is 8000. A higher number will decrease sensitivity for motion detection. The above commands enable/disable motion detection on system 197 when IOpin 1 is enabled/disabled on system 219.

ECHO_TOGGLE=219:1:1:197:echo 173 > /dr1/agent/motion_trigger
ECHO_TOGGLE=219:1:0:197:rm -f /dr1/agent/motion_trigger
The above commands enables/disables siren/alarm triggering when motion is detected on the applicable camera. The first command tells the camera that system 173 should be triggered. By default IOpin 0 should is set to 1. To enabled other actions add echo commands based on IOpin 0 of the siren system.



Button configuration:
OFFICE_HOURS=[NO|YES] (to only allow access on working days 6am - 18pm)

ON_DESKTOP_BUTTONS (to display automation buttons on desktop browser in addition to Mobile App)

Buttons switches an IO pin on for a period of time (or can toggle it on or off).

BUTTON=Label of Button:IO_Pin:(seconds to keep open):[Confirm]( before sending instruction):SystemID
BUTTON=Label of Button:IO_Pin:[toggle]::SystemID

Note: Button colours can be specified adding the colour specification to the end of the label separated by double-semi-colons:
Label of Button;;#background-color-code;;#text-and-border-color-code
Eg. BUTTON=Panic;;#FFCC7F;;#FF2C2C:...

Examples:

BUTTON=Front Gate:1:1:Confirm:195
BUTTON=Peet Garage:2:1::195
BUTTON=Maggie Garage:3:1::195

BUTTON=Office Back Door:0:2::202
BUTTON=Office Gate:0:2::195

BUTTON=Alarm:4:1::195

BUTTON=Pool:0:toggle::206

BUTTON=Pump:1:toggle::171
BUTTON=Pump 10min:1:600::171

Complete parameter set for buttons:

BUTTON=Label:IO_Pin:toggle|secs:Confirm:SysID:Input:InputType:InputSys:Location

Proximity requirement: Add LOC60 to require proximity to location 60. Ensure that location 60 has GPS coordinates. (eg. LOC60)

Buttons that execute a system command:

BUTTON=Label:CMD:/path/command::123

Buttons that set or toggle a system parameter:

BUTTON=Label:Parameter:name_of_parameter,toggle|value

Reversing the state of the GPIO output
If the GPIO pin toggle's the RELAY in the wrong state, add a minus (-) in front of the GPIO pin above (for TOGGLE & switch delays). Eg. BUTTON=Alarm:-4:1::195


Expanding sections for Buttons:

BUTTON=Label:OpenSection
buttons...
BUTTON=Label:CloseSection

Triggers / Echo button actions:

Triggers or Echos are used to create actions on other systems (or same system) when a button is pressed. It can be based on an IO Pin condition in a specific system or just the click of a button. The result / command executed by a trigger/echo can be an IO_Pin state change, Camera snapshot, OS command or SMS.

When the system detects a button press, it will check the IO_Pin and (optional state) for a match. If a match is found, the command is sent to the remote system. There has to be a remote system for an echo trigger, as the action is sent to the system and executed on that system. In the case of an SMS it is also sent to the system to initiate the SMS. The logic is that the remote system has to be alive to execute the command.

ECHO_TOGGLE=SystemID:IO_Pin:[0|1](optional match value):remoteSystemID:[remoteIO_Pin|os command]

Examples:

ECHO_TOGGLE=178:1::195:0
ECHO_TOGGLE=178:1:1:195:os command
ECHO_TOGGLE=178:1:1:178:sms0821234567This is the message
ECHO_TOGGLE=178:1:1:199:FETCH_CAM_LAST (fetches 1 image)
ECHO_TOGGLE=178:1:1:199:FETCH_CAM_N5 (fetches 5 images)
ECHO_TOGGLE=Parameter:name_of_parameter:[val]:123:os command



METRIC EVENT BASE CONFIGURATION:

In the Error handling section of a metric, place the following in either the "Change Bad" or "Change Good" text box.

AUTOMATION=SystemID-[on|off]IO_Pin,s(seconds sleep),[on|off]IO_Pin;OtherSystemID-s(sleep seconds),[on|off]IO_Pin,s(sleep seconds),[on|off]IO_Pin

Example:

AUTOMATION=171-on1,s500,off1;195-s60,on5,s420,off5

(You can build a set of sequences using on, off or s. This is set for a specific system (which can be a remote module). The on and off is followed by and IO Pin number.
The s is followed by a number of seconds (to add a delay).
A list of systems are concatenated by a semi-colon (;).
The commands per system are concatenated by a comma (,).
A system is followed by a dash (-) and then the list of commands.



Customer Content

If you need to embed custom content from a webpage (Orax SDI), use the following:


API Remote IO

If you need to switch or check state of an IO pin from a remote location over HTTPS, use the below API calls. First setup a secure remote IO code in the applicable System. To do this, go to the Update tab on the System and add the below code to the "Automation Config". Create your own secure code (this is just an example).

SECURE-REMOTE-IO-CODE:abcDE-Secure-code

Use this code in your API call (do not add colons to the secure code as a colon is used to separate the code and the system ID.

API Call to switch: https://company.oraxsdi.com/api/Remote-IO&SystemID:SECURE-REMOTE-IO-CODE&Pin:State&RAW
API Call to check state: https://company.oraxsdi.com/api/Remote-IO-State&SystemID:SECURE-REMOTE-IO-CODE&Pin&RAW
API Call to check metric state: https://company.oraxsdi.com/api/Remote-Metric-State&SystemID:SECURE-REMOTE-IO-CODE&MetricID&RAW

Eg.
curl "https://orax.oraxsdi.com/api/Remote-IO-State&248:aB2-Jsl-K55-MnBv-22-sHs7J&1&RAW"

WEBPAGE=MyPage.html


Custom Web Page buttons

In cases where the automation control is manually created with the Orax SDI's web module using HTML, you may use the following guidelines to create buttons that trigger remote automation devices/actions. The below targets control automation.

Call the agent_page function and pass the CLICKBACK command. Add the following Parameters:

1. SystemID
2. IO Pin or OS Command
3. Return URL, encrypted in Orax SDI

Simple IO Pin button
Click target: /xc?agent_page&CLICKBACK&195&1&rs24hD0z47...

Toggle button
Click target: /xc?agent_page&CLICKBACK&206&0,toggle,&rs24hD0z40a...

Custom command button
Click target: /xc?agent_page&CLICKBACK&195&gpio write 1 1; sleep 1; gpio write 1 0; sleep 2; gpio write 1 1; sleep 1; gpio write 1 0; sleep 6; gpio write 1 1; sleep 1; gpio write 1 0&rs24hD0z4...