SensorMaster Library

From wiki.amiga.org
(Difference between revisions)
Jump to: navigation, search
(Created page with "<pre> TABLE OF CONTENTS sensormaster/main/EndNotify sensormaster/main/FullSensorTable sensormaster/main/ReadFromManyByType sensormaster/main/ReadFromOneSensor sensormaster/ma...")
 
 
Line 50: Line 50:
  
 
   INPUTS
 
   INPUTS
buffer : pointer to an already allocated buffer to receive the buffer table
+
buffer : pointer to an already allocated buffer to receive the buffer table.
.
+
  length : size of the buffer above. This should be sized in according to what TotalSensors() return.
  length : size of the buffer above. This should be sized in according to wh
+
at
+
TotalSensors() return.
+
 
   
 
   
 
   RESULT
 
   RESULT
Line 76: Line 73:
  
 
   NAME
 
   NAME
       ReadFromManyByType -- Returns all readings for one kind of sensor (by u
+
       ReadFromManyByType -- Returns all readings for one kind of sensor (by unit of measure) only.
nit of measure) only.
+
  
 
   SYNOPSIS
 
   SYNOPSIS
       uint32 ReadFromManyByType(const enum UnitOfMeasure Unit, struct FullSen
+
       uint32 ReadFromManyByType(const enum UnitOfMeasure Unit, struct FullSensorReading * const Buffer, const uint32 buffer_size);
sorReading * const Buffer, const uint32 buffer_size);
+
  
 
   FUNCTION
 
   FUNCTION
This function is intended for those clients that only care about monitoring
+
This function is intended for those clients that only care about monitoring ONE kind of measure, might it be fans, voltages or anything else currently supported.
ONE kind of measure, might it be fans, voltages or anything else currently supported.
+
 
   
 
   
 
   INPUTS
 
   INPUTS
Unit The unit of measure you want to know about: see libraries/hm_sensor.h  
+
Unit The unit of measure you want to know about: see libraries/hm_sensor.h for definitions.
for definitions.
+
  Buffer A pre-allocated buffer to hold enough items. Note that this will be filled with FullSensorReading entries!
  Buffer A pre-allocated buffer to hold enough items. Note that this will be
+
filled with FullSensorReading entries!
+
 
  Buffer_size The size of said buffer.
 
  Buffer_size The size of said buffer.
  
Line 111: Line 103:
  
 
   SYNOPSIS
 
   SYNOPSIS
       BOOL ReadFromOneSensor(const uint32 index, SensorLevelType * const stor
+
       BOOL ReadFromOneSensor(const uint32 index, SensorLevelType * const storage);
age);
+
  
 
   FUNCTION
 
   FUNCTION
Line 118: Line 109:
 
   
 
   
 
   INPUTS
 
   INPUTS
index: which sensor to read. This index corresponds to the position of this
+
index: which sensor to read. This index corresponds to the position of this sensor
sensor
+
  in the table returned by TotalSensors(ANY_UNIT) or si_Index in the table returned
  in the table returned by TotalSensors(ANY_UNIT) or si_Index in the table r
+
eturned
+
 
  by SensorTableByType().
 
  by SensorTableByType().
 
   
 
   
Line 128: Line 117:
 
   RESULT
 
   RESULT
 
   
 
   
       BOOL: success. Returns TRUE if the read was successfull, FALSE if eith
+
       BOOL: success. Returns TRUE if the read was successfull, FALSE if either 'index' is too large or said sensor is not readable.
er 'index' is too large or
+
said sensor is not readable.
+
  
 
   EXAMPLE
 
   EXAMPLE
Line 149: Line 136:
  
 
   SYNOPSIS
 
   SYNOPSIS
       uint32 SensorTableByType(struct SensorIdent * buffer, const uint32 leng
+
       uint32 SensorTableByType(struct SensorIdent * buffer, const uint32 length, const enum UnitOfMeasure type);
th, const enum UnitOfMeasure type);
+
  
 
   FUNCTION
 
   FUNCTION
Line 176: Line 162:
  
 
   SYNOPSIS
 
   SYNOPSIS
       BOOL StartNotify(const uint32 sensor_number, const SensorLevelType leve
+
       BOOL StartNotify(const uint32 sensor_number, const SensorLevelType level, enum SensorCondition condition, const struct MsgPort * const call_me_maybe, const uint32 userdata);
l, enum SensorCondition condition, const struct MsgPort * const call_me_maybe, const uint32 userdata);
+
  
 
   FUNCTION
 
   FUNCTION
Registers for a notification upon level change. This function *MUST* be pai
+
Registers for a notification upon level change. This function *MUST* be paired with a corresponding call to EndNotify().
red with a corresponding call to EndNotify().
+
  Internally, it allocates a full TriggerMessage on the caller's behalf, and sends it via PutMsg()
  Internally, it allocates a full TriggerMessage on the caller's behalf, and
+
sends it via PutMsg()
+
 
  to the sensormaster notification process.
 
  to the sensormaster notification process.
  Once a notification is started, the caller must wait on the supplied Messa
+
  Once a notification is started, the caller must wait on the supplied Message Port.
ge Port.
+
  Multiple notifications can be active at the same time; if this is the case,
  Multiple notifications can be active at the same time; if this is the case
+
to distinguish between different notifications, the caller can use the "token" parameter.
,
+
to distinguish between different notifications, the caller can use the "tok
+
en" parameter.
+
 
   
 
   
  Once the caller receives the notification (via a properly filled-up Trigge
+
  Once the caller receives the notification (via a properly filled-up TriggerMessage), it  
rMessage), it  
+
 
  must call EndNotify().
 
  must call EndNotify().
 
   
 
   
 
   INPUTS
 
   INPUTS
sensor_number: the number of sensor this trigger refers to. Sensors are num
+
sensor_number: the number of sensor this trigger refers to. Sensors are numbered from 0
bered from 0
+
 
  and found via FullSensorTable() (or SensorTableByType() ).
 
  and found via FullSensorTable() (or SensorTableByType() ).
 
   
 
   
  level: the level you want to trigger the sensor on. Remember to use values
+
  level: the level you want to trigger the sensor on. Remember to use values consistent with the type  
consistent with the type  
+
 
  of each sensor. Check for those in include/hm_sensor.h.
 
  of each sensor. Check for those in include/hm_sensor.h.
 
   
 
   
  condition: to be paired with the above, one of SC_BELOW, SC_ABOVE, SC_EXA
+
  condition: to be paired with the above, one of SC_BELOW, SC_ABOVE, SC_EXACT.
CT.
+
 
  SC_BELOW and SC_ABOVE respectively resolve to <= and >= .
 
  SC_BELOW and SC_ABOVE respectively resolve to <= and >= .
 
  Don't use SC_EXACT unless you really mean it.
 
  Don't use SC_EXACT unless you really mean it.
Line 212: Line 188:
 
  call_me_maybe: message port to send the TriggerMessage back to.
 
  call_me_maybe: message port to send the TriggerMessage back to.
 
   
 
   
  userdata: can be anything the user-program wants to. It'll be put in the T
+
  userdata: can be anything the user-program wants to. It'll be put in the TriggerMessage
riggerMessage
+
structure that'll be sent back to the message port, in the tm_UserData field.
structure that'll be sent back to the message port, in the tm_UserData fiel
+
d.
+
 
   
 
   
 
   RESULT
 
   RESULT
       APTR : an opaque handle representing the trigger. To be passed to EndN
+
       APTR : an opaque handle representing the trigger. To be passed to EndNotify() to deallocate
otify() to deallocate
+
 
  associated resources.
 
  associated resources.
  
Line 256: Line 229:
 
   FUNCTION
 
   FUNCTION
 
Returns the total number of sensors available in the system.
 
Returns the total number of sensors available in the system.
  The unit of measure parameter can be used to filter out what kind you want
+
  The unit of measure parameter can be used to filter out what kind you want.
.
+
 
   
 
   
 
   INPUTS
 
   INPUTS
Unit : which unit of measure the sensors belong to. You can supply ANY_UNIT
+
Unit : which unit of measure the sensors belong to. You can supply ANY_UNIT(conveniently numbered 0)
(conveniently numbered 0)
+
 
  to have the complete number.
 
  to have the complete number.
 
   
 
   
 
   RESULT
 
   RESULT
       uint32 : the total number of sensor for the type supplied in "Unit" or
+
       uint32 : the total number of sensor for the type supplied in "Unit" or all of them if ANY_UNIT was used.
all of them if ANY_UNIT was used.
+
  
 
   EXAMPLE
 
   EXAMPLE
Line 289: Line 259:
 
   
 
   
 
   INPUTS
 
   INPUTS
index: index for the sensor to write, as seen in the full sensor table retu
+
index: index for the sensor to write, as seen in the full sensor table returned by FullSensorTable() or in SensorIdent->si_Index from SensorTableByType().
rned by FullSensorTable() or in SensorIdent->si_Index from SensorTableByType().
+
 
   
 
   
 
   RESULT
 
   RESULT

Latest revision as of 14:38, 28 October 2018

TABLE OF CONTENTS

sensormaster/main/EndNotify
sensormaster/main/FullSensorTable
sensormaster/main/ReadFromManyByType
sensormaster/main/ReadFromOneSensor
sensormaster/main/SensorTableByType
sensormaster/main/StartNotify
sensormaster/main/TotalSensors
sensormaster/main/WriteToOneSensor
sensormaster/main/EndNotify                       sensormaster/main/EndNotify

   NAME
      EndNotify -- Removes resources allocated by StartNotify().

   SYNOPSIS
      BOOL EndNotify(const APTR Trigger);

   FUNCTION
 		This is the clean-up function to be called after StartNotify().
 
   INPUTS
		APTR Trigger : The APTR resulting from calling StartNotify()
 
   RESULT
       BOOL : Wheather it succeded or not.
 		

   EXAMPLE
		See StartNotify() for a (somewhat) complete example.
 
   NOTES
		You must call EndNotify even on notifications that haven't been triggered.
 
   BUGS

   SEE ALSO
	StartNotify(), libraries/sensormaster.h , libraries/hm_sensor.h

sensormaster/main/FullSensorTable           sensormaster/main/FullSensorTable

   NAME
      FullSensorTable -- Return the full table of available sensors.

   SYNOPSIS
      uint32 FullSensorTable(void * const buffer, const uint32 length);

   FUNCTION

   INPUTS
		buffer : pointer to an already allocated buffer to receive the buffer table.
 		length : size of the buffer above. This should be sized in according to what TotalSensors() return.
 
   RESULT
       uint32: The actual amount of data written to the buffer.

   EXAMPLE
 		const size_t s_table_size = sizeof(Sensor) * TotalSensors();
 		buffer = AllocVecTags(s_table_size, TAG_DONE);
 		uint32 result = FullSensorTable(buffer, s_table_size);
 		[use it]
 		FreeVec(s_table_size);
 
   NOTES

   BUGS

   SEE ALSO
		TotalSensors(), libraries/sensormaster.h
 
sensormaster/main/ReadFromManyByType     sensormaster/main/ReadFromManyByType

   NAME
      ReadFromManyByType -- Returns all readings for one kind of sensor (by unit of measure) only.

   SYNOPSIS
      uint32 ReadFromManyByType(const enum UnitOfMeasure Unit, struct FullSensorReading * const Buffer, const uint32 buffer_size);

   FUNCTION
		This function is intended for those clients that only care about monitoring ONE kind of measure, might it be fans, voltages or anything else currently supported.
 
   INPUTS
		Unit	The unit of measure you want to know about: see libraries/hm_sensor.h for definitions.
 		Buffer	A pre-allocated buffer to hold enough items. Note that this will be filled with FullSensorReading entries!
 		Buffer_size The size of said buffer.

   RESULT
       uint32: size of the actual buffer used.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO
		ReadFromOneSensor(), SensorTableByType()
sensormaster/main/ReadFromOneSensor       sensormaster/main/ReadFromOneSensor

   NAME
      ReadFromOneSensor -- Reads a sensor value (shocker!)

   SYNOPSIS
      BOOL ReadFromOneSensor(const uint32 index, SensorLevelType * const storage);

   FUNCTION
		Reads the value from one sensor.
 
   INPUTS
		index: which sensor to read. This index corresponds to the position of this sensor
 		in the table returned by TotalSensors(ANY_UNIT) or si_Index in the table returned
 		by SensorTableByType().
 
 		storage: pointer to a destination where to write the sensor value.
 
   RESULT
 
       BOOL: success. Returns TRUE if the read was successfull, FALSE if either 'index' is too large or said sensor is not readable.

   EXAMPLE

   NOTES
		It's up to each sensor sub-library to read the value and possibly cache it.
		Thus it's possible that a value has been cached according to the polling in
terval.
 
   BUGS

   SEE ALSO

sensormaster/main/SensorTableByType       sensormaster/main/SensorTableByType

   NAME
      SensorTableByType -- Returns a table of all sensors by type.

   SYNOPSIS
      uint32 SensorTableByType(struct SensorIdent * buffer, const uint32 length, const enum UnitOfMeasure type);

   FUNCTION

   INPUTS
		buffer: A properly allocated buffer for SensorIdent structures
 		length: the length of the buffer.
 		type: which type of sensor you want.
 
   RESULT
       uint32: the actual size of the buffer that was used (written to).

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO

sensormaster/main/StartNotify                   sensormaster/main/StartNotify

   NAME
      StartNotify -- Register for notification on sensor level change.

   SYNOPSIS
      BOOL StartNotify(const uint32 sensor_number, const SensorLevelType level, enum SensorCondition condition, const struct MsgPort * const call_me_maybe, const uint32 userdata);

   FUNCTION
		Registers for a notification upon level change. This function *MUST* be paired with a corresponding call to EndNotify().
 		Internally, it allocates a full TriggerMessage on the caller's behalf, and sends it via PutMsg()
 		to the sensormaster notification process.
 		Once a notification is started, the caller must wait on the supplied Message Port.
 		Multiple notifications can be active at the same time; if this is the case,
		to distinguish between different notifications, the caller can use the "token" parameter.
 
 		Once the caller receives the notification (via a properly filled-up TriggerMessage), it 
 		must call EndNotify().
 
   INPUTS
		sensor_number: the number of sensor this trigger refers to. Sensors are numbered from 0
 		and found via FullSensorTable() (or SensorTableByType() ).
 
 		level: the level you want to trigger the sensor on. Remember to use values consistent with the type 
 		of each sensor. Check for those in include/hm_sensor.h.
 
 		condition: to be paired with the above, one of 	SC_BELOW, SC_ABOVE, SC_EXACT.
 		SC_BELOW and SC_ABOVE respectively resolve to <= and >= .
 		Don't use SC_EXACT unless you really mean it.
 
 		call_me_maybe: message port to send the TriggerMessage back to.
 
 		userdata: can be anything the user-program wants to. It'll be put in the TriggerMessage
		structure that'll be sent back to the message port, in the tm_UserData field.
 
   RESULT
       APTR : an opaque handle representing the trigger. To be passed to EndNotify() to deallocate
 		associated resources.

   EXAMPLE
	MsgPort * mport = (MsgPort*)IExec->AllocSysObjectTags(ASOT_PORT,
											ASOPORT_AllocSig, TRUE,
											ASOPORT_Action, PA_SIGNAL,
											ASOPORT_Target, IExec->FindTask(NULL),
											TAG_DONE);
	APTR handle=nullptr;
	handle = StartNotify(16, 300l, SC_BELOW, mport, 666);

	if(handle != nullptr)
		{
		IExec->WaitPort(mport);
		//Trigger arrived!!
		EndNotify(handle);
		}
			

   NOTES

   BUGS

   SEE ALSO
	EndNotify(), libraries/sensormaster.h , libraries/hm_sensor.h

sensormaster/main/TotalSensors                 sensormaster/main/TotalSensors

   NAME
      TotalSensors -- Returns total number of sensors.

   SYNOPSIS
      uint32 TotalSensors(const enum UnitOfMeasure unit);

   FUNCTION
		Returns the total number of sensors available in the system.
 		The unit of measure parameter can be used to filter out what kind you want.
 
   INPUTS
		Unit : which unit of measure the sensors belong to. You can supply ANY_UNIT(conveniently numbered 0)
 		to have the complete number.
 
   RESULT
       uint32 : the total number of sensor for the type supplied in "Unit" or all of them if ANY_UNIT was used.

   EXAMPLE

   NOTES

   BUGS
	Sheesh! My code is perfect!
 
   SEE ALSO
	SensorTableByType() , libraries/hm_sensor.h
sensormaster/main/WriteToOneSensor         sensormaster/main/WriteToOneSensor

   NAME
      WriteToOneSensor -- Writes to one sensor. No surprise there.

   SYNOPSIS
      BOOL WriteToOneSensor(const uint32 index, const SensorLevelType value);

   FUNCTION
		Writes the supplied value to the sensor specified in 'index'.
 
   INPUTS
		index: index for the sensor to write, as seen in the full sensor table returned by FullSensorTable() or in SensorIdent->si_Index from SensorTableByType().
 
   RESULT
       BOOL: success. True if the sensor allows writing to it.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO
		FullSensorTable(), SensorTableByType()
Personal tools
Namespaces

Variants
Actions
Navigation
Tools