Python Helper Methods

Let's start:

  • download the helper.
  • unzip it.
  • import ZeusAPI.py.

Client Constructor

Create a new instance of the Client class and establishes the connection to the Zeus Server.

You can obtain your authaccount and authpass once logged on ZeusWeb, going to URL: api_credentials.html.

Parameters:

  • IP. String. IP of the Server.
  • Port. String. Port of the server. For example: "4040".
  • SSL. Boolean. Use SSL. For example: True.
  • Authaccount. String. The authaccount you can get on Zeus Web URL: api_credentials.html. Please check that user has the property "API enabled" in the Server.
  • Password. String. Zeus Web account password.
  • Authpass. String. The authpass you can get on Zeus Web URL: api_credentials.html

Check that the object was created using the IsCreated function. If it returns False, use the GetZeusApiLastError function to get more information about the error. Some examples of errors:

  • Parameters: The input parameters are incorrect.
  • Conection: Unable to connect to Server.
  • Authentication: Request Authentication incorrect.

IsCreated

Returns a Boolean indicating if the client is created.

GetZeusApiLastError

Returns a String indicating the last error in ZeusApi.

GetLastKnownValues

Gets the last known values of a station.

Parameters:

  • stationID. String. ID (ZeusID) of the station.

Returns a dict object, a standar class that has the following members or None if an error occurred:

  • lastConnectionTime. datetime with the date of last connection time.
  • RSSI. Integer. Received Signal Strength Indication (RSSI).
  • PowerSupply. String. Can be an Integer with Voltage or a String with "green" (good condition), "orange" (must replace batteries in 3 months) or "red" (must replace batteries within current month).
  • values. dict (String, Float). Every key corresponding to Channels Enumeration.

GetLastKnownValuesExtended

Gets the station extended last known values like lastConnectionTime, RSSI, PowerSupply, values... Contain all members returned by the GetLastKnownValues function plus new fields (the number of fields returned may vary with future versions).

Parameters:

  • stationID. String. ID (ZeusID) of the station.

Returns a dict (String, object) or none if an error occurred. Contains the name of the variable and its value. For example:

  • ["lastConnectionTime"] = String with the Date into the format dd-mm-yyyy;hh:mm:ss.fff (UTC)
  • ["RSSI"] = Integer. Received Signal Strength Indication (RSSI).
  • ["PowerSupply"] = String. Can be an Integer with Voltage or a String with "green" (good condition), "orange" (must replace batteries in 3 months) or "red" (must replace batteries within current month).
  • ["Carrier"] = String. The device carrier.
  • ["RAT"] = String. The device RAT.
  • ["RunStop"] = Boolean. The device support RunStop.
  • ["values"] = Associative Arrays (String, Single). Every key corresponding to Channels Enumeration.

GetAllLastKnownValues

Gets the last known values of all stations.

Returns an dict (String, dict) that has the following members or None if an error occurred:

  • lastConnectionTime. String with the Date into the format dd-mm-yyyy;hh:mm:ss.fff (UTC)
  • RSSI. Integer. Received Signal Strength Indication (RSSI).
  • PowerSupply. String. Can be an Integer with Voltage or a String with "green" (good condition), "orange" (must replace batteries in 3 months) or "red" (must replace batteries within current month).
  • values. dict (String, Single). Every key corresponding to Channels Enumeration.

GetAllStationLastKnownValuesExtended

Gets the extended last known values of all stations.

Returns an dict (String, dict(String, Object)) or none if an error occurred. The key is the ZeusID and the Associative Array(String, Object) has the following members:

  • ["lastConnectionTime"] = String with the Date into the format dd-mm-yyyy;hh:mm:ss.fff (UTC)
  • ["RSSI"] = Integer. Received Signal Strength Indication (RSSI).
  • ["PowerSupply"] = String. Can be an Integer with Voltage or a String with "green" (good condition), "orange" (must replace batteries in 3 months) or "red" (must replace batteries within current month).
  • ["Carrier"] = String. The device carrier.
  • ["RAT"] = String. The device RAT.
  • ["RunStop"] = Boolean. The device support RunStop.
  • ["values"] = dict (String, Single). Every key corresponding to Channels Enumeration.

SetLastKnownValues

Sets the last known values of a station.

Parameters:

  • stationID. String. ID (ZeusID) of the station.
  • values. LastKnownValues. Values of the station to upload. LastKnownValues is a simple class that has the following members:

    • lastConnectionTime. datetime. Timestamp of values (UTC).
    • RSSI. Integer. Received Signal Strength Indication (RSSI).
    • PowerSupply. String. Can be an Integer with Voltage or a String with "green" (good condition), "orange" (must replace batteries in 3 months) or "red" (must replace batteries within current month).
    • values. dict(Of String, Single). Every key corresponding to Channels Enumeration.

Returns True if everything went OK, or False if there was some problem. You can look in the GetZeusApiLastError variable to get more details in case of error.

SetLastKnownValuesExtended

Sets the extended last known values of a station. Set all members of SetLastKnownValues function plus new fields (the number of fields may vary with future versions).

Parameters:

  • stationID. String. ID (ZeusID) of the station.
  • values. dict (String, Object). Values of SetLastKnownValues function plus new fields to upload:
    • ["lastConnectionTime"] = String with the Date into the format dd-mm-yyyy;hh:mm:ss.fff (UTC)
    • ["RSSI"] = Integer. Received Signal Strength Indication (RSSI).
    • ["PowerSupply"] = String. Can be an Integer with Voltage or a String with "green" (good condition), "orange" (must replace batteries in 3 months) or "red" (must replace batteries within current month).
    • ["Carrier"] = String. The device carrier.
    • ["RAT"] = String. The device RAT.
    • ["RunStop"] = Boolean. The device support RunStop.
    • ["values"] = dict (String, Single). Every key corresponding to Channels Enumeration.

Returns True if everything went OK, or False if there was some problem. You can look in the GetZeusApiLastError variable to get more details in case of error.

GetStationProperties

DEPRECATED: Please use GetStationExtendedProperties instead

Gets the station properties like model, serial, group, latitude, longitude, name and unit of every channel and channel views.

Parameters:

  • stationID. String. ID (ZeusID) of the station.

Returns a stdClass object, a standar class that has the following members or None if an error occurred:

  • Model. String. The model of the device, for example "NEMOS_N200", "HERMES_M100", etc.
  • Serial. String. The device serial number.
  • Latitude. String. GPS latitude, in decimal format.
  • Longitude. String. GPS longitude, in decimal format.
  • Group. String. Zeus Group.
  • Reference1. String. Reference 1 field filled on Zeus Server Stations tab, usually containing more info or some reference of internal use.
  • Reference2. String. Reference 2 field filled on Zeus Server Stations tab, usually containing more info or some reference of internal use.
  • ChannelNames. dict. Dict of names for every channel. Every index corresponding to Channels Enumeration.
  • ChannelUnits. dict. Array of units for every channel. Every index corresponding to Channels Enumeration.
  • ChannelViews. dict(String, dict(String)). Dict of channel views, containing at least the view "Default" (the default graph view on Zeus), or any other view configured for this station inside "Views" tab on Zeus Server.

GetStationExtendedProperties

Gets the station extended properties like name, ZeusID, model, serial, group, latitude, longitude, name and unit of every channel and channel views... Contain all members returned by the GetStationProperties function plus new fields (the number of fields returned may vary with future versions).

Parameters:

  • stationID. String. ID (ZeusID) of the station.

Returns a dict (String, object) or None if an error occurred. Contains the name of the variable and its value. For example:

  • ["Name"] = String. Alias/Name of the device.
  • ["ZeusID"] = String. ZeusID of the device.
  • ["Model"] = String. The model of the device, for example "NEMOS_N200", "HERMES_M100", etc.
  • ["Serial"] = String. The device serial number.
  • ["Latitude"] = String. GPS latitude, in decimal format.
  • ["Longitude"] = String. GPS longitude, in decimal format.
  • ["Group"] = String. Zeus Group.
  • ["Reference1"] = String. Reference 1 field filled on Zeus Server Stations tab, usually containing more info or some reference of internal use.
  • ["Reference2"] = String. Reference 2 field filled on Zeus Server Stations tab, usually containing more info or some reference of internal use.
  • ["ChannelsNames"] = String List. List of names for every channel. Every index corresponding to Channels Enumeration.
  • ["ChannelsUnits"] = String List. List of units for every channel. Every index corresponding to Channels Enumeration.
  • ["ChannelsViews"] = dict (String, list(Of String)). Dictionary of channel views, containing at least the view "Default" (the default graph view on Zeus), or any other view configured for this station inside "Views" tab on Zeus Server.
  • ["BatteryVoltageIsLow"] = Boolean. True if device battery needs to be replaced soon.

GetAllStationProperties

DEPRECATED: Please use GetAllStationExtendedProperties instead

Gets properties of all stations like model, serial, group, latitude, longitude, name and unit of every channel and channel views.

Returns an dict (String, object) or None if an error occurred. This object is a standar class that has the following members that has the following members:

  • Model. String. The model of the device, for example "NEMOS_N200", "HERMES_M100", etc.
  • Serial. String. The device serial number.
  • Latitude. String. GPS latitude, in decimal format.
  • Longitude. String. GPS longitude, in decimal format.
  • Group. String. Zeus Group.
  • Reference1. String. Reference 1 field filled on Zeus Server Stations tab, usually containing more info or some reference of internal use.
  • Reference2. String. Reference 2 field filled on Zeus Server Stations tab, usually containing more info or some reference of internal use.
  • ChannelNames. list (String). List of names for every channel. Every index corresponding to Channels Enumeration.
  • ChannelUnits. list (String). List of units for every channel. Every index corresponding to Channels Enumeration.
  • ChannelViews. dict (String, list(String)). Dict of channel views, containing at least the view "Default" (the default graph view on Zeus), or any other view configured for this station inside "Views" tab on Zeus Server.

GetAllStationExtendedProperties

Gets extended properties of all stations like name, ZeusID, model, serial, group, latitude, longitude, name and unit of every channel and channel views... Contain all members returned by the GetStationProperties function plus new fields (the number of fields returned may vary with future versions).

Returns a dict (String, dict(String, Object)) or None if an error occurred. Contains ZeusID of station and a Array with the name of the variable and its value. For example:

  • ["Name"] = String. Alias/Name of the device.
  • ["ZeusID"] = String. ZeusID of the device.
  • ["Model"] = String. The model of the device, for example "NEMOS_N200", "HERMES_M100", etc.
  • ["Serial"] = String. The device serial number.
  • ["Latitude"] = String. GPS latitude, in decimal format.
  • ["Longitude"] = String. GPS longitude, in decimal format.
  • ["Group"] = String. Zeus Group.
  • ["Reference1"] = String. Reference 1 field filled on Zeus Server Stations tab, usually containing more info or some reference of internal use.
  • ["Reference2"] = String. Reference 2 field filled on Zeus Server Stations tab, usually containing more info or some reference of internal use.
  • ["ChannelsNames"] = String list. List of names for every channel. Every index corresponding to Channels Enumeration.
  • ["ChannelsUnits"] = String Llst. List of units for every channel. Every index corresponding to Channels Enumeration.
  • ["ChannelsViews"] = List(Of String, List(Of String)). Dictionary of channel views, containing at least the view "Default" (the default graph view on Zeus), or any other view configured for this station inside "Views" tab on Zeus Server.
  • ["BatteryVoltageIsLow"] = Boolean. True if device battery needs to be replaced soon.

Stations

Gets the list of stations of this user.

Returns a List (String), containing the list of stations this user can access or None if an error occurred:

OnlineStations

Gets the list of stations currently online (connected to server) of this user.

Returns a List (String), containing the list of stations currently online (connected to server) from the list of stations this user can access or None if an error occurred:

SendMessage

Sends a message to the specified station or phone number.

Parameters:

  • destination. String. ID (ZeusID) of the station ,(or the phone number, only if sendBySMS parameter is True)
  • messageText. String. The text of the message to be sent.
  • sendBySMS (OPTIONAL). Boolean. Indicates if the message should be sent by SMS or enqueued to the Server for the next time the station connects to the server.

Returns True if message was sent or enqueued succesfully, or False if there was some problem. You can look in the GetZeusApiLastError variable to get more details in case of error.

PendingMessages

Gets the list of pending messages enqueued for stations of this user.

Returns a list (dcit (Key: String, Value: String)), where keys are Stations IDs and Values are message texts or None if an error occurred:

GetHistorical

Gets historical values of the specified station, date interval, and list of channels.

Parameters:

  • stationID. String. ID (ZeusID) of the station.
  • startDate. datetime. The begin date of the interval of historical you are asking for.
  • endDate. datetime. The end date of the interval of historical you are asking for.
  • channels. List (Integer). List of channels IDs. See Channels Enumeration.

datetime is a simple class that extends DateTime PHP Class. The use and members are the same.

Returns a dict, a standar class that has the following members or None if an error occurred:

  • DateOfRecord. String. with the Date into the format dd-mm-yyyy;hh:mm:ss.fff.
  • ChannelID. Integer. Channel ID of the record. See Channels Enumeration.
  • Reason. String. Reason of the record. See Reasons Enumeration
  • Value. Single. The value of the record.

SetHistorical

Uploads a list of historical values of the specified station.

Parameters:

  • stationID. String. ID (ZeusID) of the station.
  • historicalValues. List (of Historical) objects, a simple class that has the following members:

    • DateOfRecord. datetime. Timestamp of values.
    • ChannelID. Integer. Channel ID of the record. See Channels Enumeration.
    • Reason. String. Reason of the record. See Reasons Enumeration.
    • Value. Single. The value of the record.

datetime is a simple class that extends DateTime PHP Class. The use and members are the same.

Returns True if historical was sent succesfully, or False if there was some problem. You can look in the GetZeusApiLastError variable to get more details in case of error.

GetAlarm

Gets alarms values of the specified date interval.

Parameters:

  • startDate. datetime. The begin date of the interval of alarms you are asking for.
  • endDate. datetime. The end date of the interval of alarms you are asking for.
  • sinceThisRawValue (OPTIONAL). String. If you prefer, instead of using startDate and endDate, you can specify the raw value of an alarm record, so you will get records after that alarm. When using this, startDate and endDate values will be omitted.

Returns a dict, a standar class that has the following members or None if an error occurred:

  • StationID. String. ID (ZeusID) of the station.
  • DateOfRecord. String. with the Date into the format dd-mm-yyyy;hh:mm:ss.fff.
  • Reason. Integer. Reason of the record. See Reasons Enumeration.
  • ChannelID. Integer. ChannelID of the Alarm.
  • AlarmText. String. The text of the alarm. For example: "TEMPERATURE OUT OF RANGE".
  • RawValue. String. The raw string of the alarm, coded as Zeus stores it, for use as reference for future queries.

SetAlarms

Uploads a list of alarms values of the specified station.

Parameters:

  • alarmValues. Array (of Alarms) objects, a simple class that has the following members:

    • StationID. String. ID (ZeusID) of the station.
    • DateOfRecord. datetime. Timestamp of values.
    • Reason. Integer. Reason of the record. Usual values are: 1 (High Value), 2 (Low Value), 3 (Back to normal value or restored value), 5 (Alarm activation in digital input). See Reasons Enumeration.
    • ChannelID. Integer. ChannelID of the Alarm.
    • AlarmText. String. The text of the alarm. For example: "TEMPERATURE OUT OF RANGE".
    • RawValue. String. Just leave it empty ("") as it's not needed for uploading purposes.

Returns True if alarms was sent succesfully, or False if there was some problem. You can look in the GetZeusApiLastError variable to get more details in case of error.

GetConfigurationRelay

Gets the programmable relay period of a station.

Parameters:

  • stationID. String. ID (ZeusID) of the station.
  • output. Integer. output of the station.

Returns a dict, a standar class that has the following members or None if an error occurred:

  • Weekdays. List (Of String). List of days of the week (L,M,X,J,V,S,D).
  • ActivationTime. String. Time with the format hh:mm indicating the activation time.
  • Duration. Integer. Duration (seconds) of the period.

SetConfigurationRelay

Set a ProgrammableRelayPeriod to the specified station.

Parameters:

  • destination. String. ID (ZeusID) of the station.
  • output. String. The output to configure.
  • myFrameTime. List (Of ProgrammableRelayPeriod). List that contains a maximum of 4 elements with the configuration..

Returns True if configuration was sent, or False if there was some problem. You can look in the GetZeusApiLastError variable to get more details in case of error.