Difference between revisions of "Unit PWM"

Latest revision as of 03:37, 15 December 2022

This unit deals with the usage of PWM for control applications (for audio applications see the Audio unit) and provides methods to control the state, frequency, duty cycle, range and mode of PWM host controllers. Not all devices support all of these concepts so this API includes a properties function to allow obtaining information about a PWM device and its capabilities.

Constants

PWM specific constants PWM_*

`PWM_NAME_PREFIX = 'PWM';`	Name prefix for PWM Devices

PWM device type PWM_TYPE_*

`PWM_TYPE_NONE = 0;`

`PWM_TYPE_MAX = 0;`

PWM device state PWM_STATE_*

`PWM_STATE_DISABLED = 0;`
`PWM_STATE_ENABLED = 1;`

PWM device flag PWM_FLAG_*

`PWM_FLAG_NONE = $00000000;`
`PWM_FLAG_GPIO = $00000001;`	Device supports Get/Set GPIO
`PWM_FLAG_MODE = $00000002;`	Device supports Get/Set Mode
`PWM_FLAG_RANGE = $00000004;`	Device supports Get/Set Range
`PWM_FLAG_FREQUENCY = $00000008;`	Device supports Get/Set Frequency
`PWM_FLAG_POLARITY = $00000010;`	Device supports Get/Set Polarity

PWM mode value PWM_MODE_*

`PWM_MODE_MARKSPACE = 0;`	Standard PWM Mark/Space mode
`PWM_MODE_BALANCED = 1;`	Balanced mode (Device specific)
`PWM_MODE_SERIALIZED = 2;`	Serialized mode (Device specific)

`PWM_MODE_MAX = 2;`

PWM polarity value PWM_POLARITY_*

`PWM_POLARITY_NORMAL = 0;`
`PWM_POLARITY_INVERSE = 1;`

`PWM_POLARITY_MAX = 1;`

PWM logging PWM_LOG_*

`PWM_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;`	PWM debugging messages
`PWM_LOG_LEVEL_INFO = LOG_LEVEL_INFO;`	PWM informational messages, such as a device being attached or detached
`PWM_LOG_LEVEL_WARN = LOG_LEVEL_WARN;`	PWM warning messages
`PWM_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;`	PWM error messages
`PWM_LOG_LEVEL_NONE = LOG_LEVEL_NONE;`	No PWM messages

Type definitions

PWM properties

PPWMProperties = ^TPWMProperties;

TPWMProperties = record

`Flags:LongWord;`	Device flags (eg PWM_FLAG_MODE)
`GPIO:LongWord;`
`Mode:LongWord;`
`Range:LongWord;`
`Frequency:LongWord;`
`Polarity:LongWord;`
`DutyNS:LongWord;`
`PeriodNS:LongWord;`
`MinPeriod:LongWord;`

PWM enumeration callback

`TPWMEnumerate = function(PWM:PPWMDevice; Data:Pointer):LongWord;`

PWM notification callback

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

PWM device start

`TPWMDeviceStart = function(PWM:PPWMDevice):LongWord;`

PWM device stop

`TPWMDeviceStop = function(PWM:PPWMDevice):LongWord;`

PWM device write

`TPWMDeviceWrite = function(PWM:PPWMDevice; Value:LongWord):LongWord;`

PWM device get GPIO

`TPWMDeviceGetGPIO = function(PWM:PPWMDevice):LongWord;`

PWM device set GPIO

`TPWMDeviceSetGPIO = function(PWM:PPWMDevice; GPIO:LongWord):LongWord;`

PWM device get mode

`TPWMDeviceGetMode = function(PWM:PPWMDevice):LongWord;`

PWM device set mode

`TPWMDeviceSetMode = function(PWM:PPWMDevice; Mode:LongWord):LongWord;`

PWM device get range

`TPWMDeviceGetRange = function(PWM:PPWMDevice):LongWord;`

PWM device set range

`TPWMDeviceSetRange = function(PWM:PPWMDevice; Range:LongWord):LongWord;`

PWM device get frequency

`TPWMDeviceGetFrequency = function(PWM:PPWMDevice):LongWord;`

PWM device set frequency

`TPWMDeviceSetFrequency = function(PWM:PPWMDevice; Frequency:LongWord):LongWord;`

PWM device get polarity

`TPWMDeviceGetPolarity = function(PWM:PPWMDevice):LongWord;`

PWM device set polarity

`TPWMDeviceSetPolarity = function(PWM:PPWMDevice; Polarity:LongWord):LongWord;`

PWM device configure

`TPWMDeviceConfigure = function(PWM:PPWMDevice; DutyNS,PeriodNS:LongWord):LongWord;`

PWM device get properties

`TPWMDeviceGetProperties = function(PWM:PPWMDevice; Properties:PPWMProperties):LongWord;`

PWM device

PPWMDevice = ^TPWMDevice;

TPWMDevice = record

Device Properties
`Device:TDevice;`	The Device entry for this PWM
PWM Properties
`PWMId:LongWord;`	Unique Id of this PWM in the PWM table
`PWMState:LongWord;`	PWM state (eg PWM_STATE_ENABLED)
`DeviceStart:TPWMDeviceStart;`	A Device specific DeviceStart method implementing the standard PWM device interface (Mandatory)
`DeviceStop:TPWMDeviceStop;`	A Device specific DeviceStop method implementing the standard PWM device interface (Mandatory)
`DeviceWrite:TPWMDeviceWrite;`	A Device specific DeviceWrite method implementing the standard PWM device interface (Mandatory)
`DeviceGetGPIO:TPWMDeviceGetGPIO;`	A Device specific DeviceGetGPIO method implementing the standard PWM device interface (Or nil if the operation is not supported)
`DeviceSetGPIO:TPWMDeviceSetGPIO;`	A Device specific DeviceSetGPIO method implementing the standard PWM device interface (Or nil if the operation is not supported)
`DeviceGetMode:TPWMDeviceGetMode;`	A Device specific DeviceGetMode method implementing the standard PWM device interface (Or nil if the operation is not supported)
`DeviceSetMode:TPWMDeviceSetMode;`	A Device specific DeviceSetMode method implementing the standard PWM device interface (Or nil if the operation is not supported)
`DeviceGetRange:TPWMDeviceGetRange;`	A Device specific DeviceGetRange method implementing the standard PWM device interface (Or nil if the operation is not supported)
`DeviceSetRange:TPWMDeviceSetRange;`	A Device specific DeviceSetRange method implementing the standard PWM device interface (Or nil if the operation is not supported)
`DeviceGetFrequency:TPWMDeviceGetFrequency;`	A Device specific DeviceGetFrequency method implementing the standard PWM device interface (Or nil if the operation is not supported)
`DeviceSetFrequency:TPWMDeviceSetFrequency;`	A Device specific DeviceSetFrequency method implementing the standard PWM device interface (Or nil if the operation is not supported)
`DeviceGetPolarity:TPWMDeviceGetPolarity;`	A Device specific DeviceGetPolarity method implementing the standard PWM device interface (Or nil if the operation is not supported)
`DeviceSetPolarity:TPWMDeviceSetPolarity;`	A Device specific DeviceSetPolarity method implementing the standard PWM device interface (Or nil if the operation is not supported)
`DeviceConfigure:TPWMDeviceConfigure;`	A Device specific DeviceConfigure method implementing the standard PWM device interface (Mandatory)
`DeviceGetProperties:TPWMDeviceGetProperties;`	A Device specific DeviceGetProperties method implementing the standard PWM device interface (Or nil if the default method is suitable)
Statistics Properties
`GetCount:LongWord;`
`SetCount:LongWord;`
`WriteCount:LongWord;`
`ConfigCount:LongWord;`
Driver Properties
`Lock:TMutexHandle;`	Device lock
`GPIO:LongWord;`	GPIO Pin
`Mode:LongWord;`	Device Mode
`Range:LongWord;`	Device Range
`Frequency:LongWord;`	Clock Frequency
`Polarity:LongWord;`	Output Polarity
`DutyNS:LongWord;`	Duty Nanoseconds
`PeriodNS:LongWord;`	Period Nanonseconds
`Properties:TPWMProperties;`	Device properties
Internal Properties
`Prev:PPWMDevice;`	Previous entry in PWM table
`Next:PPWMDevice;`	Next entry in PWM table

Public variables

PWM logging

`PWM_DEFAULT_LOG_LEVEL:LongWord = PWM_LOG_LEVEL_DEBUG;`	Minimum level for PWM messages. Only messages with level greater than or equal to this will be printed.

`PWM_LOG_ENABLED:Boolean;`

Function declarations

Initialization functions

procedure PWMInit;

Description: Initialize the PWM unit and PWM device table

Note	Called only during system startup

PWM functions

function PWMDeviceStart(PWM:PPWMDevice):LongWord;

Description: Start the specified PWM device

PWM	The PWM device to start
Return	ERROR_SUCCESS if completed or another error code on failure

function PWMDeviceStop(PWM:PPWMDevice):LongWord;

Description: Stop the specified PWM device

PWM	The PWM device to stop
Return	ERROR_SUCCESS if completed or another error code on failure

function PWMDeviceWrite(PWM:PPWMDevice; Value:LongWord):LongWord;

Description: Write a value to the specified PWM device

PWM	The PWM device to write to
Value	The value to write
Return	ERROR_SUCCESS if completed or another error code on failure
Note	The exact meaning of value may depend on the device and other configured options, in many cases the value will represent the "on" time of each pulse with regard to the duty cycle of the waveform output by the device.

function PWMDeviceGetGPIO(PWM:PPWMDevice):LongWord;

Description: Get the GPIO pin used by the specified PWM device

PWM	The PWM device to get the GPIO pin from
Return	The current GPIO pin or GPIO_PIN_UNKNOWN on failure

function PWMDeviceSetGPIO(PWM:PPWMDevice; GPIO:LongWord):LongWord;

Description: Set the GPIO pin used by the specified PWM device

PWM	The PWM device to set the GPIO pin for
GPIO	The GPIO pin to set (eg GPIO_PIN_12)
Return	ERROR_SUCCESS if completed or another error code on failure

function PWMDeviceGetMode(PWM:PPWMDevice):LongWord;

Description: Get the current mode of the specified PWM device

PWM	The PWM device to get the mode from
Return	The current mode or a default value of PWM_MODE_MARKSPACE

function PWMDeviceSetMode(PWM:PPWMDevice; Mode:LongWord):LongWord;

Description: Set the current mode for the specified PWM device

PWM	The PWM device to set the mode for
Mode	The mode value to set (eg PWM_MODE_MARKSPACE)
Return	ERROR_SUCCESS if completed or another error code on failure

function PWMDeviceGetRange(PWM:PPWMDevice):LongWord;

Description: Get the current range of the specified PWM device

PWM	The PWM device to get the range from
Return	The current range or 0 on failure

function PWMDeviceSetRange(PWM:PPWMDevice; Range:LongWord):LongWord;

Description: Set the current range for the specified PWM device

PWM	The PWM device to set the clock rate for
Range	The range value to set
Return	ERROR_SUCCESS if completed or another error code on failure
Note	The exact meaning of range may depend on the device and other configured options, in many cases the range will represent the period of one full cycle of the waveform output by the device.

function PWMDeviceGetFrequency(PWM:PPWMDevice):LongWord;

Description: Get the clock frequency of the specified PWM device

PWM	The PWM device to get the clock frequency from
Return	The clock frequency in Hz or 0 on failure

function PWMDeviceSetFrequency(PWM:PPWMDevice; Frequency:LongWord):LongWord;

Description: Set the clock frequency for the specified PWM device

PWM	The PWM device to set the clock frequency for
Frequency	The clock frequency to set in Hz
Return	ERROR_SUCCESS if completed or another error code on failure

function PWMDeviceGetPolarity(PWM:PPWMDevice):LongWord;

Description: Get the current polarity of the specified PWM device

PWM	The PWM device to get the polarity from
Return	The current polarity or a default value of PWM_POLARITY_NORMAL

function PWMDeviceSetPolarity(PWM:PPWMDevice; Polarity:LongWord):LongWord;

Description: Set the current polarity for the specified PWM device

PWM	The PWM device to set the polarity for
Polarity	The polarity value to set (eg PWM_POLARITY_NORMAL)
Return	ERROR_SUCCESS if completed or another error code on failure

function PWMDeviceConfigure(PWM:PPWMDevice; DutyNS,PeriodNS:LongWord):LongWord;

Description: Set the configuration of the specified PWM device

PWM	The PWM device to set the configuration for
DutyNS	The "on" time part of the cycle (Nanoseconds)
PeriodNS	The duration of one full cycle (Nanoseconds)
Return	ERROR_SUCCESS if completed or another error code on failure

function PWMDeviceProperties(PWM:PPWMDevice; Properties:PPWMProperties):LongWord; inline;

Description: Get the properties for the specified PWM device

PWM	The PWM device to get properties from
Properties	Pointer to a TPWMProperties structure to fill in
Return	ERROR_SUCCESS if completed or another error code on failure
Note	Replaced by PWMDeviceGetProperties for consistency

function PWMDeviceGetProperties(PWM:PPWMDevice; Properties:PPWMProperties):LongWord;

Description: Get the properties for the specified PWM device

PWM	The PWM device to get properties from
Properties	Pointer to a TPWMProperties structure to fill in
Return	ERROR_SUCCESS if completed or another error code on failure

function PWMDeviceCreate:PPWMDevice;

Description: Create a new PWM entry

Return	Pointer to new PWM entry or nil if PWM could not be created

function PWMDeviceCreateEx(Size:LongWord):PPWMDevice;

Description: Create a new PWM entry

Size	Size in bytes to allocate for new PWM (Including the PWM entry)
Return	Pointer to new PWM entry or nil if PWM could not be created

function PWMDeviceDestroy(PWM:PPWMDevice):LongWord;

Description: Destroy an existing PWM entry

Note	None documented

function PWMDeviceRegister(PWM:PPWMDevice):LongWord;

Description: Register a new PWM in the PWM table

Note	None documented

function PWMDeviceDeregister(PWM:PPWMDevice):LongWord;

Description: Deregister a PWM from the PWM table

Note	None documented

function PWMDeviceFind(PWMId:LongWord):PPWMDevice;

Description: To be documented

Note	None documented

function PWMDeviceFindByName(const Name:String):PPWMDevice; inline;

Description: To be documented

Note	None documented

function PWMDeviceFindByDescription(const Description:String):PPWMDevice; inline;

Description: To be documented

Note	None documented

function PWMDeviceEnumerate(Callback:TPWMEnumerate; Data:Pointer):LongWord;

Description: To be documented

Note	None documented

function PWMDeviceNotification(PWM:PPWMDevice; Callback:TPWMNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;

Description: To be documented

Note	None documented

RTL PWM functions

function SysPWMAvailable:Boolean;

Description: Check if a PWM device is available

Note	None documented

function SysPWMStart:LongWord;

Description: Start the default PWM device

Return	ERROR_SUCCESS if completed or another error code on failure

function SysPWMStop:LongWord;

Description: Stop the default PWM device

Return	ERROR_SUCCESS if completed or another error code on failure

function SysPWMWrite(Value:LongWord):LongWord;

Description: Write a value to the default PWM device

Value	The value to write
Return	ERROR_SUCCESS if completed or another error code on failure
Note	The exact meaning of value may depend on the device and other configured options, in many cases the value will represent the "on" time of each pulse with regard to the duty cycle of the waveform output by the device.

function SysPWMSetMode(Mode:LongWord):LongWord;

Description: Set the mode for the default PWM device

Mode	The mode value to set (eg PWM_MODE_MARKSPACE)
Return	ERROR_SUCCESS if completed or another error code on failure

function SysPWMSetRange(Range:LongWord):LongWord;

Description: Set the range for the default PWM device

Range	The range value to set
Return	ERROR_SUCCESS if completed or another error code on failure
Note	The exact meaning of range may depend on the device and other configured options, in many cases the range will represent the period of one full cycle of the waveform output by the device.

function SysPWMSetFrequency(Frequency:LongWord):LongWord;

Description: Set the clock frequency for the default PWM device

Frequency	The frequency to set in Hz
Return	ERROR_SUCCESS if completed or another error code on failure

function SysPWMConfigure(DutyNS,PeriodNS:LongWord):LongWord;

Description: Set the configuration of the default PWM device

DutyNS	The "on" time part of the cycle (Nanoseconds)
PeriodNS	The duration of one full cycle (Nanoseconds)
Return	ERROR_SUCCESS if completed or another error code on failure

PWM helper functions

function PWMGetCount:LongWord;

Description: Get the current PWM count

Note	None documented

function PWMDeviceGetDefault:PPWMDevice;

Description: Get the current default PWM device

Note	None documented

function PWMDeviceSetDefault(PWM:PPWMDevice):LongWord;

Description: Set the current default PWM device

Note	None documented

function PWMDeviceCheck(PWM:PPWMDevice):PPWMDevice;

Description: Check if the supplied PWM is in the PWM table

Note	None documented

function PWMTypeToString(PWMType:LongWord):String;

Description: Convert a PWM type value to a string

Note	None documented

function PWMStateToString(PWMState:LongWord):String;

Description: Convert a PWM state value to a string

Note	None documented

function PWMModeToString(PWMMode:LongWord):String;

Description: Convert a PWM mode value to a string

Note	None documented

function PWMPolarityToString(PWMPolarity:LongWord):String;

Description: Convert a PWM polarity value to a string

Note	None documented

procedure PWMLog(Level:LongWord; PWM:PPWMDevice; const AText:String);

Description: To be documented

Note	None documented

procedure PWMLogInfo(PWM:PPWMDevice; const AText:String); inline;

Description: To be documented

Note	None documented

procedure PWMLogWarn(PWM:PPWMDevice; const AText:String); inline;

Description: To be documented

Note	None documented

procedure PWMLogError(PWM:PPWMDevice; const AText:String); inline;

Description: To be documented

Note	None documented

procedure PWMLogDebug(PWM:PPWMDevice; const AText:String); inline;

Description: To be documented

Note	None documented

Return to Unit Reference

@@ Line 5: / Line 5: @@
 ----
-'''Ultibo PWM interface unit'''
+'''Ultibo PWM Interface unit'''
 Pulse Width Modulation (PWM) is a technique of encoding a pulsed signal so as to control the ratio of on to off by switching the signal between on and off at a very high rate.
@@ Line 37: / Line 37: @@
 | <code>PWM_TYPE_NONE = 0;</code>
 | style="width: 50%;"|&nbsp;
+|-
+|colspan="2"|&nbsp;
+|-
+| <code>PWM_TYPE_MAX = 0;</code>
+| &nbsp;
 |-
 |}
@@ Line 94: / Line 99: @@
 | <code>PWM_MODE_SERIALIZED = 2;</code>
 | Serialized mode (Device specific)
+|-
+|colspan="2"|&nbsp;
+|-
+| <code>PWM_MODE_MAX = 2;</code>
+| &nbsp;
 |-
 |}
@@ Line 107: / Line 117: @@
 |-
 | <code>PWM_POLARITY_INVERSE = 1;</code>
+| &nbsp;
+|-
+|colspan="2"|&nbsp;
+|-
+| <code>PWM_POLARITY_MAX = 1;</code>
 | &nbsp;
 |-
@@ Line 1,024: / Line 1,039: @@
 <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
-<pre style="border: 0; padding-bottom:0px;">function PWMGetCount:LongWord; inline;</pre>
+<pre style="border: 0; padding-bottom:0px;">function PWMGetCount:LongWord;</pre>
 <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the current PWM count</div>
 <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
@@ Line 1,036: / Line 1,051: @@
 <br />
 <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
-<pre style="border: 0; padding-bottom:0px;">function PWMDeviceGetDefault:PPWMDevice; inline;</pre>
+<pre style="border: 0; padding-bottom:0px;">function PWMDeviceGetDefault:PPWMDevice;</pre>
 <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the current default PWM device</div>
 <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
@@ Line 1,062: / Line 1,077: @@
 <pre style="border: 0; padding-bottom:0px;">function PWMDeviceCheck(PWM:PPWMDevice):PPWMDevice;</pre>
 <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if the supplied PWM is in the PWM table</div>
+<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
+{| class="wikitable" style="font-size: 14px; background: white;"
+|-
+! Note
+| None documented
+|-
+|}
+</div></div>
+<br />
+<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
+<pre style="border: 0; padding-bottom:0px;">function PWMTypeToString(PWMType:LongWord):String;</pre>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Convert a PWM type value to a string</div>
+<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
+{| class="wikitable" style="font-size: 14px; background: white;"
+|-
+! Note
+| None documented
+|-
+|}
+</div></div>
+<br />
+<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
+<pre style="border: 0; padding-bottom:0px;">function PWMStateToString(PWMState:LongWord):String;</pre>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Convert a PWM state value to a string</div>
+<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
+{| class="wikitable" style="font-size: 14px; background: white;"
+|-
+! Note
+| None documented
+|-
+|}
+</div></div>
+<br />
+<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
+<pre style="border: 0; padding-bottom:0px;">function PWMModeToString(PWMMode:LongWord):String;</pre>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Convert a PWM mode value to a string</div>
+<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
+{| class="wikitable" style="font-size: 14px; background: white;"
+|-
+! Note
+| None documented
+|-
+|}
+</div></div>
+<br />
+<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
+<pre style="border: 0; padding-bottom:0px;">function PWMPolarityToString(PWMPolarity:LongWord):String;</pre>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Convert a PWM polarity value to a string</div>
 <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 {| class="wikitable" style="font-size: 14px; background: white;"

Difference between revisions of "Unit PWM"

Latest revision as of 03:37, 15 December 2022

Contents

Description

Constants

Type definitions

Public variables

Function declarations

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools