A PWM (Pulse-Width Modulator) is a component used for controlling power to inertial electrical devices. It generates a periodic waveform with positive width which can be controlled and thus, the waveform’s average value modified.
The average value of voltage fed to the load is controlled by turning the switch between the supply and the load on and off at a fast pace. The longer the switch is on compared to the off, the higher the power supplied to the load will be.
The ConnectCore 8X has several PWM (Pulse Width Modulation) interfaces to manage devices such as servos and voltage regulators. In the ConnectCore 8X Hardware Reference Manual you can find information about the available PWM channels.
Digi adds to Android an API to manage these PWM channels. You can configure the PWM duty cycle, the frequency, and the polarity among other things. In the Digi APIx javadoc you can find a complete list of the available methods in this API.
Unless noted, all PWM API methods require the com.digi.android.permission.PWM permission.
If your application does not have the com.digi.android.permission.PWM permission it will not have access to any PWM service feature.
|
First of all, a new PWMManager object must be instantiated by passing the Android Application Context.
import android.app.Activity;
import android.os.Bundle;
import com.digi.android.pwm.PWMManager;
public class PWMSampleActivity extends Activity {
PWMManager pwmManager;
[...]
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Instantiate the PWM manager object.
pwmManager= new PWMManager(this);
[...]
}
[...]
}Instantiate a PWM channel
The PWMManager allows you to create a PWM object representing a physical module’s PWM channel.
To create a PWM object you will need a PWMChip object and the PWM channel index.
If you don’t know how many chips and channels are available in the device you can list them.
| Method | Description |
|---|---|
|
Lists all available PWM chips in the device |
|
Lists all available PWM channels in the |
|
Creates and returns a |
The createPWM(PWMChip, int) method may fail if the provided chip or channel is not available, throwing a PWMException.
import com.digi.android.pwm.PWM;
import com.digi.android.pwm.PWMChip;
import com.digi.android.pwm.PWMManager;
[...]
PWMManager pwmManager = ...;
// Create a PWM object for each available PWM channel.
List<PWM> pwms = new ArrayList<>();
List<PWMChip> chips = pwmManager.listPWMChips();
for (PWMChip chip : chips) {
List<Integer> channels = chip.listChannels();
for (int channel : channels) {
pwms.add(pwmManager.createPWM(chip, channel));
}
}
[...]Manage PWM period/frequency
You can get and set the PWM channel period or frequency using the following methods:
| Method | Description |
|---|---|
|
Returns the PWM channel period in nanoseconds |
|
Changes the period of the PWM channel to the given nanoseconds |
|
Returns the PWM channel frequency in Hz |
|
Changes the PWM channel frequency in Hz |
These methods may fail if there is any error while reading or configuring the PWM period/frequency, throwing a PWMException.
import com.digi.android.pwm.PWM;
import com.digi.android.pwm.PWMChip;
import com.digi.android.pwm.PWMManager;
[...]
PWMManager pwmManager = ...;
PWM pwm = ...;
[...]
System.out.println("PWM chip: " + pwm.getChip());
System.out.println("PWM channel: " + pwm.getChannelIndex());
System.out.println("Period (ns): " + pwm.getPeriod());
System.out.println("Frequency (Hz): " + pwm.getFrequency());
// Set period to 500ms
pwm.setPeriod(500000000);
System.out.println("New period (ns): " + pwm.getPeriod());
// Set frequency to 1000Hz
pwm.setFrequency(1000);
System.out.println("New frequency (Hz): " + pwm.getFrequency());
[...]
Before you configure the period/frequency:
* make sure the channel is disabled.
* make sure the configured duty cycle is lower than the new period.
If you attempt to configure a period lower than the configured duty cycle, or configure the period/frequency while the channel is enabled, the system will throw a PWMException.
|
Manage PWM duty cycle
You can get and set the PWM channel duty cycle using the following methods:
| Method | Description |
|---|---|
|
Returns the duty cycle the PWM channel in nanoseconds |
|
Changes the duty cycle of the PWM channel to the given nanoseconds |
|
Returns the duty cycle percentage of the PWM channel (0 to 100%) |
|
Changes the duty cycle percentage of the PWM channel |
These methods may fail if there is any error while reading or configuring the PWM duty cycle, throwing a PWMException.
import com.digi.android.pwm.PWM;
import com.digi.android.pwm.PWMChip;
import com.digi.android.pwm.PWMManager;
[...]
PWMManager pwmManager = ...;
PWM pwm = ...;
[...]
System.out.println("PWM chip: " + pwm.getChip());
System.out.println("PWM channel: " + pwm.getChannelIndex());
System.out.println("Duty cycle (ns): " + pwm.getDutyCycleRaw());
System.out.println("Duty cycle (%): " + pwm.getDutyCyclePercentage());
// Set duty cycle to 50%
pwm.setDutyCyclePercentage(50);
System.out.println("New duty cycle (%): " + pwm.getDutyCyclePercentage());
long period = pwm.getPeriod();
pwm.setDutyCycleRaw(period/2);
System.out.println("New duty cycle (ns): " + pwm.getDutyCycleRaw());
[...]
Before you configure the duty cycle in raw mode, make sure the configured period is greater than the new duty cycle.
If you attempt to configure a duty cycle greater than the configured period, the system will throw a PWMException.
|
Manage PWM polarity
You can get and set the PWM channel polarity using the PWMPolarity enumeration class and the following methods:
| Method | Description |
|---|---|
|
Returns the polarity of the PWM channel |
|
Changes the polarity of the PWM channel |
These methods may fail if there is any error while reading or configuring the PWM polarity, throwing a PWMException.
import com.digi.android.pwm.PWM;
import com.digi.android.pwm.PWMChip;
import com.digi.android.pwm.PWMManager;
import com.digi.android.pwm.PWMPolarity;
[...]
PWMManager pwmManager = ...;
PWM pwm = ...;
[...]
System.out.println("PWM chip: " + pwm.getChip());
System.out.println("PWM channel: " + pwm.getChannelIndex());
System.out.println("Polarity: " + pwm.getPolarity());
// Change polarity.
pwm.setPolarity(PWMPolarity.NORMAL);
System.out.println("New polarity: " + pwm.getPolarity());
pwm.setPolarity(PWMPolarity.INVERSED);
System.out.println("New polarity: " + pwm.getPolarity());
[...]
Before you configure the polarity, make sure the period is greater than zero.
If you attempt to configure the polarity when the period is zero, the system will throw a PWMException.
|
Manage PWM enable status
You can enable or disable the PWM channel using the following methods:
| Method | Description |
|---|---|
|
Returns |
|
Changes the enable status of the PWM channel |
These methods may fail if there is any error while reading or configuring the PWM enable status, throwing a PWMException.
import com.digi.android.pwm.PWM;
import com.digi.android.pwm.PWMChip;
import com.digi.android.pwm.PWMManager;
[...]
PWMManager pwmManager = ...;
PWM pwm = ...;
[...]
System.out.println("PWM chip: " + pwm.getChip());
System.out.println("PWM channel: " + pwm.getChannelIndex());
System.out.println("Enabled: " + pwm.isEnabled());
// Change enable status.
pwm.setEnabled(false);
System.out.println("New enable status: " + pwm.isEnabled());
pwm.setEnabled(true);
System.out.println("New enable status: " + pwm.isEnabled());
[...]
Before you enable the channel, make sure the configured period is greater than zero.
If you attempt to enable the channel when the period is zero, the system will throw a PWMException.
|
PWM example
The PWM Sample Application demonstrates the usage of the PWM API. In this example you can list all the available PWM chips and channels and configure the different PWM parameters.
You can import the example using Digi’s Android Studio plugin. For more information, see Import a Digi sample application. To look at the application source code, go to the GitHub repository.
