Difference between revisions of "Custom Drivers Command and Utility Methods API"

From HSYCO
Jump to navigation Jump to search
(Created page with "== Constants == === LIGHT === LIGHT === AUTOM === AUTOM === DIMMER === DIMMER === BINARY === BINARY == System Functions == === dateSet === boolean dateSet(int year,...")
 
Line 3: Line 3:
 
=== LIGHT ===
 
=== LIGHT ===
 
  LIGHT
 
  LIGHT
 +
 +
Used for the function field of deviceSet().
  
 
=== AUTOM ===
 
=== AUTOM ===
 
  AUTOM
 
  AUTOM
 +
 +
Used for the function field of deviceSet().
  
 
=== DIMMER ===
 
=== DIMMER ===
 
  DIMMER
 
  DIMMER
 +
 +
Used for the function field of deviceSet().
  
 
=== BINARY ===
 
=== BINARY ===
 
  BINARY
 
  BINARY
 +
 +
Used for the function field of deviceSet().
  
 
== System Functions ==
 
== System Functions ==
Line 17: Line 25:
 
=== dateSet ===
 
=== dateSet ===
 
  boolean dateSet(int year, int month, int day, int hour, int minute, int second)
 
  boolean dateSet(int year, int month, int day, int hour, int minute, int second)
 +
 +
Sets the HSYCO Server operating system’s clock and hardware clock, in the local time zone.
 +
 +
 +
'''Parameters:'''
 +
 +
* year: int - the year, greater than 1900
 +
* month: int - the month, between 1-12
 +
* day: int - the day, between 1-31
 +
* hour: int - the hour, between 0-23
 +
* minute: int - the minute, between 0-59
 +
* second: int - the second, between 0-59.
 +
 +
 +
'''Returns:'''
 +
 +
* boolean - true if successful, false if not.
  
 
=== getNextSunrise ===
 
=== getNextSunrise ===
 
  long getNextSunrise(long now, boolean withoffset)
 
  long getNextSunrise(long now, boolean withoffset)
 +
 +
Computes the time of the next sunrise after the time set in the now parameter.
 +
 +
The sunrise time is returned in milliseconds since midnight, January 1, 1970 UTC.
 +
 +
 +
'''Parameters:'''
 +
 +
* now: long - the reference time in milliseconds
 +
* withoffset: boolean - true to take the sunrise offset into account, as defined with the SunriseOffsetMinutes in hsyco.ini, false to ignore the offset and return the actual sunrise time (Based on civil dawn, begins when the geometric center of the sun is 6° below the horizon).
 +
 +
 +
'''Returns:'''
 +
 +
* long - the next sunrise time in milliseconds since midnight, January 1, 1970 UTC.
  
 
=== getNextSunset ===
 
=== getNextSunset ===
 
  long getNextSunset(long now, boolean withoffset)
 
  long getNextSunset(long now, boolean withoffset)
 +
 +
Computes the time of the next sunset after the time set in the now parameter.
 +
 +
The sunset time is returned in milliseconds since midnight, January 1, 1970 UTC.
 +
 +
 +
'''Parameters:'''
 +
 +
* now: long - the reference time in milliseconds
 +
* withoffset: boolean - true to take the sunset offset into account, as defined with the SunriseOffsetMinutes in hsyco.ini, false to ignore the offset and return the actual sunrise time (Based on civil dusk, ends when the geometric center of the sun reaches 6° below the horizon).
 +
 +
 +
'''Returns:'''
 +
 +
* long - the next sunset time in milliseconds since midnight, January 1, 1970 UTC.
  
 
=== haActiveState ===
 
=== haActiveState ===
 
  boolean haActiveState()
 
  boolean haActiveState()
 +
 +
When HSYCO is installed in a high availability configuration, this method returns true if the system (master or slave) is active, false if it is not active.
 +
 +
If high availability is not configured, the method returns true.
 +
 +
 +
'''Returns:'''
 +
 +
* boolean - high availability current state.
 +
 +
=== haActive ===
 +
static void haActive(boolean active)
 +
 +
Force a master HSYCO server to become inactive, or return to the active state.
 +
 +
This method should be called on the master only, and has no effect on the slave server.
 +
 +
 +
'''Parameters:'''
 +
 +
* active: boolean - set to true to force a master to become inactive, or false to return it to the active state after the master was forced to become inactive.
  
 
=== sleep ===
 
=== sleep ===
 
  void sleep(long millis)
 
  void sleep(long millis)
 +
 +
Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds.
 +
 +
 +
'''Parameters:'''
 +
 +
* millis: long - the length of time to sleep in milliseconds.
  
 
=== varGet ===
 
=== varGet ===
 
  String varGet(String name)
 
  String varGet(String name)
 +
 +
Returns the value of a program variable, or null if no variable with the given name has been defined.
 +
 +
Program variables can be set using varSet() in user.java or in the EVENTS programming environment.
 +
 +
To access a variable used in EVENTS, the name used in varGet() should start with the $ character.
 +
 +
Variables names ending with ! are considered persistent and their values are preserved when HSYCO restarts; normal variables are deleted when HSYCO starts.
 +
 +
 +
'''Parameters:'''
 +
 +
* name: String - the variable name. Names are case-insensitive.
 +
 +
 +
'''Returns:'''
 +
 +
* String - the current value of the program variable.
  
 
=== varSet ===
 
=== varSet ===
 
  void varSet(String name, String value)
 
  void varSet(String name, String value)
 +
 +
Sets a program variable to the value parameter.
 +
 +
Variables set with varSet() can be read using varGet() and are also available in the EVENTS programming environment, if the variable name starts with $.
 +
 +
If you need to use variables in Java or JavaScript but don’t want these variables to be available in EVENTS, just use names that don’t start with the $ character.
 +
 +
Variables names ending with ! are considered persistent and their values are preserved when HSYCO restarts; normal variables are deleted when HSYCO starts.
 +
 +
 +
'''Parameters:'''
 +
 +
* name: String - the variable name. Names are case-insensitive
 +
* value: String - the value to be assigned to the program variable.
  
 
== Driver Control ==
 
== Driver Control ==
Line 41: Line 156:
 
  boolean init(String name)
 
  boolean init(String name)
  
−
=== commandPoll ===
+
Must be called once inside the init() callback.
−
String commandPoll(int millis)
+
 
 +
<syntaxhighlight lang="java">
 +
public class Driver extends driverBase {
 +
 +
public boolean init(String name, HashMap<String, String> config) {
 +
 +
super.init(name); // do not remove
 +
return true;
 +
}
 +
}
 +
</syntaxhighlight>
 +
 
 +
 
 +
'''Parameters:'''
 +
 
 +
* name: String - the driver's identifier.
  
 
== Driver I/O ==
 
== Driver I/O ==
Line 48: Line 178:
 
=== ioSet ===
 
=== ioSet ===
 
  void ioSet(String name, String value)
 
  void ioSet(String name, String value)
 +
 +
Writes back a command to this driver.
 +
 +
This method should only be used to push back a command to the command queue, to be processed again after all currently pending commands.
 +
 +
 +
'''Parameters:'''
 +
 +
* id: String - the data point name, without the I/O server id prefix
 +
* value: String - the new value.
  
 
=== ioWrite ===
 
=== ioWrite ===

Revision as of 13:25, 19 February 2014

Constants

LIGHT

LIGHT

Used for the function field of deviceSet().

AUTOM

AUTOM

Used for the function field of deviceSet().

DIMMER

DIMMER

Used for the function field of deviceSet().

BINARY

BINARY

Used for the function field of deviceSet().

System Functions

dateSet

boolean dateSet(int year, int month, int day, int hour, int minute, int second)

Sets the HSYCO Server operating system’s clock and hardware clock, in the local time zone.


Parameters:

  • year: int - the year, greater than 1900
  • month: int - the month, between 1-12
  • day: int - the day, between 1-31
  • hour: int - the hour, between 0-23
  • minute: int - the minute, between 0-59
  • second: int - the second, between 0-59.


Returns:

  • boolean - true if successful, false if not.

getNextSunrise

long getNextSunrise(long now, boolean withoffset)

Computes the time of the next sunrise after the time set in the now parameter.

The sunrise time is returned in milliseconds since midnight, January 1, 1970 UTC.


Parameters:

  • now: long - the reference time in milliseconds
  • withoffset: boolean - true to take the sunrise offset into account, as defined with the SunriseOffsetMinutes in hsyco.ini, false to ignore the offset and return the actual sunrise time (Based on civil dawn, begins when the geometric center of the sun is 6° below the horizon).


Returns:

  • long - the next sunrise time in milliseconds since midnight, January 1, 1970 UTC.

getNextSunset

long getNextSunset(long now, boolean withoffset)

Computes the time of the next sunset after the time set in the now parameter.

The sunset time is returned in milliseconds since midnight, January 1, 1970 UTC.


Parameters:

  • now: long - the reference time in milliseconds
  • withoffset: boolean - true to take the sunset offset into account, as defined with the SunriseOffsetMinutes in hsyco.ini, false to ignore the offset and return the actual sunrise time (Based on civil dusk, ends when the geometric center of the sun reaches 6° below the horizon).


Returns:

  • long - the next sunset time in milliseconds since midnight, January 1, 1970 UTC.

haActiveState

boolean haActiveState()

When HSYCO is installed in a high availability configuration, this method returns true if the system (master or slave) is active, false if it is not active.

If high availability is not configured, the method returns true.


Returns:

  • boolean - high availability current state.

haActive

static void haActive(boolean active)

Force a master HSYCO server to become inactive, or return to the active state.

This method should be called on the master only, and has no effect on the slave server.


Parameters:

  • active: boolean - set to true to force a master to become inactive, or false to return it to the active state after the master was forced to become inactive.

sleep

void sleep(long millis)

Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds.


Parameters:

  • millis: long - the length of time to sleep in milliseconds.

varGet

String varGet(String name)

Returns the value of a program variable, or null if no variable with the given name has been defined.

Program variables can be set using varSet() in user.java or in the EVENTS programming environment.

To access a variable used in EVENTS, the name used in varGet() should start with the $ character.

Variables names ending with ! are considered persistent and their values are preserved when HSYCO restarts; normal variables are deleted when HSYCO starts.


Parameters:

  • name: String - the variable name. Names are case-insensitive.


Returns:

  • String - the current value of the program variable.

varSet

void varSet(String name, String value)

Sets a program variable to the value parameter.

Variables set with varSet() can be read using varGet() and are also available in the EVENTS programming environment, if the variable name starts with $.

If you need to use variables in Java or JavaScript but don’t want these variables to be available in EVENTS, just use names that don’t start with the $ character.

Variables names ending with ! are considered persistent and their values are preserved when HSYCO restarts; normal variables are deleted when HSYCO starts.


Parameters:

  • name: String - the variable name. Names are case-insensitive
  • value: String - the value to be assigned to the program variable.

Driver Control

init

boolean init(String name)

Must be called once inside the init() callback. 

public class Driver extends driverBase {
	
	public boolean init(String name, HashMap<String, String> config) {
		
		super.init(name); // do not remove
		return true;
	}
}


Parameters:

  • name: String - the driver's identifier.

Driver I/O

ioSet

void ioSet(String name, String value)

Writes back a command to this driver.

This method should only be used to push back a command to the command queue, to be processed again after all currently pending commands.


Parameters:

  • id: String - the data point name, without the I/O server id prefix
  • value: String - the new value.

ioWrite

void ioWrite(String name, String value)

ioWriteNoLog

void ioWriteNoLog(String name, String value)

ioWriteNoEvents

void ioWriteNoEvents(String name, String value)

ioWriteNoEventsNoLog

void ioWriteNoEventsNoLog(String name, String value)

ioWriteForced

void ioWriteForced(String name, String value)

ioWriteForcedNoLog

void ioWriteForcedNoLog(String name, String value)

Log

errorLog

void errorLog(String message)

fileLog

void fileLog(String pathname, String message)

messageLog

void messageLog(String message)

Mail

sendMail

int sendMail(String to, String from, String subject, String body)

sendMail

int sendMail(String to, String from, String subject, Vector<String> body)

Public Announcement

audioPlay

int audioPlay(String where, File file)

audioPlay

int audioPlay(String where, String voice, String text)

Serial Communication Ports

closeComm

void closeComm(String portName)

readComm

String readComm(String portName, int len)

readCommBytes

byte[] readCommBytes(String portName, int len)

writeComm

int writeComm(String portName, String data)

writeCommBytes

int writeCommBytes(String portName, byte[] data)

User Interface

deviceSet

void deviceSet(int function, String device, String state, String comment)

enableSystemtopoDiscovery

void enableSystemtopoDiscovery()

uiClear

void uiClear(String session)

uiSet

void uiSet(String session, String id, String attr, String value)

uiSet

void uiSet(String id, String attr, String value)

user

void user(String name, String param)
Retrieved from "https://wiki.hsyco.com/3.7/index.php?title=Custom_Drivers_Command_and_Utility_Methods_API&oldid=2454"