Unit W1

From Ultibo.org
Revision as of 02:31, 15 December 2022 by Ultibo (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Return to Unit Reference


Description


Ultibo 1-Wire Interface unit

1-Wire is a communications bus designed by Dallas Semiconductor Corp that combines low speed signalling, data and power over a single signal line. It is often used for small devices such as digital thermometers.

Devices can actually be powered over the 1-Wire interface allowing the use of just data and ground lines.

Note: Because FreePascal does not permit the use of functions or variables that begin with a numeric value such as 1WIRE we use the term W1 throughout this unit to refer to a 1-Wire device. This is the same terminology as used in Linux and other systems.

Constants



W1 specific constants W1_*
W1_NAME_PREFIX = '1WIRE'; Name prefix for 1-Wire Devices


W1 device types W1_TYPE_*
W1_TYPE_NONE = 0;  


W1 device states W1_STATE_*
W1_STATE_DISABLED = 0;  
W1_STATE_ENABLED = 1;  


W1 device flags W1_FLAG_*
W1_FLAG_NONE = $00000000;  


W1 logging W1_LOG_*
W1_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG; W1 debugging messages
W1_LOG_LEVEL_INFO = LOG_LEVEL_INFO; W1 informational messages, such as a device being attached or detached
W1_LOG_LEVEL_WARN = LOG_LEVEL_WARN; W1 warning messages
W1_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR; W1 error messages
W1_LOG_LEVEL_NONE = LOG_LEVEL_NONE; No W1 messages


Type definitions



W1 properties

PW1Properties = ^TW1Properties;

TW1Properties = record

Flags:LongWord; Device flags (eg W1_FLAG_????)

W1 enumeration callback

TW1Enumerate = function(W1:PW1Device; Data:Pointer):LongWord;

W1 notification callback

TW1Notification = function(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;

W1 device get properties

TW1DeviceGetProperties = function(W1:PW1Device; Properties:PW1Properties):LongWord;

W1 device

PW1Device = ^TW1Device;

TW1Device = record

Device Properties
Device:TDevice; The Device entry for this W1
W1 Properties
W1Id:LongWord; Unique Id of this W1 in the W1 table
W1State:LongWord; W1 state (eg W1_STATE_ENABLED)
DeviceGetProperties:TW1DeviceGetProperties; A Device specific DeviceGetProperties method implementing the standard W1 device interface (Or nil if the default method is suitable)
Statistics Properties
 
Driver Properties
Lock:TMutexHandle; Device lock
Properties:TW1Properties; Device properties
Internal Properties
Prev:PW1Device; Previous entry in W1 table
Next:PW1Device; Next entry in W1 table


Public variables



W1 logging

W1_DEFAULT_LOG_LEVEL:LongWord = W1_LOG_LEVEL_DEBUG; Minimum level for W1 messages. Only messages with level greater than or equal to this will be printed.
W1_LOG_ENABLED:Boolean;


Function declarations



Initialization functions

procedure W1Init;
Description: Initialize the W1 unit and W1 device table
Note Called only during system startup


W1 functions

function W1DeviceGetProperties(W1:PW1Device; Properties:PW1Properties):LongWord;
Description: Get the properties for the specified W1 device
W1 The W1 device to get properties from
Properties Pointer to a TW1Properties structure to fill in
Return ERROR_SUCCESS if completed or another error code on failure


function W1DeviceCreate:PW1Device;
Description: Create a new W1 entry
Return Pointer to new W1 entry or nil if W1 could not be created


function W1DeviceCreateEx(Size:LongWord):PW1Device;
Description: Create a new W1 entry
Size Size in bytes to allocate for new W1 (Including the W1 entry)
Return Pointer to new W1 entry or nil if W1 could not be created


function W1DeviceDestroy(W1:PW1Device):LongWord;
Description: Destroy an existing W1 entry
Note None documented


function W1DeviceRegister(W1:PW1Device):LongWord;
Description: Register a new W1 in the W1 table
Note None documented


function W1DeviceDeregister(W1:PW1Device):LongWord;
Description: Deregister a W1 from the W1 table
Note None documented


function W1DeviceFind(W1Id:LongWord):PW1Device;
Description: To be documented
Note None documented


function W1DeviceFindByName(const Name:String):PW1Device; inline;
Description: To be documented
Note None documented


function W1DeviceFindByDescription(const Description:String):PW1Device; inline;
Description: To be documented
Note None documented


function W1DeviceEnumerate(Callback:TW1Enumerate; Data:Pointer):LongWord;
Description: To be documented
Note None documented


function W1DeviceNotification(W1:PW1Device; Callback:TW1Notification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: To be documented
Note None documented


W1 helper functions

function W1GetCount:LongWord;
Description: Get the current W1 count
Note None documented


function W1DeviceGetDefault:PW1Device;
Description: Get the current default W1 device
Note None documented


function W1DeviceSetDefault(W1:PW1Device):LongWord;
Description: Set the current default W1 device
Note None documented


function W1DeviceCheck(W1:PW1Device):PW1Device;
Description: Check if the supplied W1 is in the W1 table
Note None documented


procedure W1Log(Level:LongWord; W1:PW1Device; const AText:String);
Description: To be documented
Note None documented


procedure W1LogInfo(W1:PW1Device; const AText:String); inline;
Description: To be documented
Note None documented


procedure W1LogWarn(W1:PW1Device; const AText:String); inline;
Description: To be documented
Note None documented


procedure W1LogError(W1:PW1Device; const AText:String); inline;
Description: To be documented
Note None documented


procedure W1LogDebug(W1:PW1Device; const AText:String); inline;
Description: To be documented
Note None documented


Return to Unit Reference