Java Helper Methods

Let's start:

  • download the helper.
  • unzip it.
  • import ZeusAPI.java file in your project.
  • Download GSON 2.8.5 or newer and configure your IDE..
  • Download Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy and put the library in the JDK folder..

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. int. 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

Exceptions:

  • 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 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 LastKnownValues object, a simple class that has the following members or Nothing if an error occurred:

  • lastConnectionTime. Date. 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. Hashtable(Of String, Float). Every key corresponding to Channels Enumeration.

GetLastKnownValuesExtended

Gets the last known values of a station.

Parameters:

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

Returns a Hashtable(Of String, Object) or null 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"] = Hashtable (Of String, Single). Every key corresponding to Channels Enumeration.

GetAllLastKnownValues

Gets the last known values of all stations.

Returns a Hashtable(Of String, LastKnownValues) a simple class that has the following members or null if an error occurred:

  • lastConnectionTime. Date. 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. Hashtable(Of String, Float). Every key corresponding to Channels Enumeration.

GetAllStationLastKnownValuesExtended

Gets the extended last known values of all stations.

Returns an Hashtable (String, dict(Hashtable, Object)) or none if an error occurred. The key is the ZeusID and the Hashtable(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. Date. 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. Hashtable(Of String, Float). 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. Hashtable (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"] = Hashtable (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 StationProperties object, a simple class that has the following members or Nothing 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. String List. List of names for every channel. Every index corresponding to Channels Enumeration.
  • ChannelUnits. String List. List of units for every channel. Every index corresponding to Channels Enumeration.
  • ChannelViews. Hashtable(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.

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 Hashtable(Of String, Object) or null 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"] = Dictionary(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.

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 Hashtable(Of String, StationProperties), a simple class that has the following members or Nothing 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. String List. List of names for every channel. Every index corresponding to Channels Enumeration.
  • ChannelUnits. String List. List of units for every channel. Every index corresponding to Channels Enumeration.
  • ChannelViews. Hashtable(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.

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 Hashtable(Of String, Hashtable(Of String, Object)) or null if an error occurred. Contains ZeusID of station and a Dictionary 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 List. List of units for every channel. Every index corresponding to Channels Enumeration.
  • ["ChannelsViews"] = Dictionary(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 (of String), containing the list of stations this user can access or Nothing if an error occurred:

OnlineStations

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

Returns a List (of String), containing the list of stations currently online (connected to server) from the list of stations this user can access or Nothing 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 (of KeyValue(Of String, String)), where keys are Stations IDs and Values are message texts or Nothing 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. Date. The begin date of the interval of historical you are asking for.
  • endDate. Date. The end date of the interval of historical you are asking for.
  • channels. List (of Integer). List of channels IDs. See Channels Enumeration.

Returns a List of Historical objects, a simple class that has the following members or Nothing if an error occurred:

  • DateOfRecord. Date. Timestamp of the record.
  • 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. Date. Timestamp of the record.
    • 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.

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. Date. The begin date of the interval of historical you are asking for.
  • endDate. Date. The end date of the interval of historical you are asking for.
  • sinceThisRawValue. 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 List of Alarms objects, a simple class that has the following members or Nothing if an error occurred:

  • StationID. String. ID (ZeusID) of the station.
  • DateOfRecord. Date. Timestamp of the record.
  • Reason. Integer. Reason of the record. See Reasons Enumeration.
  • ChannelID. Integer. Channel ID 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. List (of Alarms) objects, a simple class that has the following members:

    • StationID. String. ID (ZeusID) of the station.
    • DateOfRecord. Date. Timestamp of the record.
    • 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. Channel ID 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 List of ProgrammableRelayPeriod object, a simple class that has the following members or Nothing 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.