Rail Entity

The Rail entity provides power control to connected devices on some modules. Check the module datasheet to determine if the module has this capability.

the Rail entity controls power provided to downstream devices, it has the ability to enable and disable power, can read voltage on the rail, and provides current consumption information on some modules. There are additional capabilities that certain modules provide which enhance basic power delivery through Kelvin sensing, or by bringing online separate power management functionality.

Certain modules may provide more than one power rail. These are independently controlled and can be accessed via the entity index.

Current (Get)

rail[ index ] . getCurrent <= (int) microamps

Returns the current consumption of the device attached to the rail. This can be a positive or negative value, and is reported in microamps.

Current Limit (Get/Set)

rail [ index ] . getCurrentLimit <= (int) microamps
rail [ index ] . setCurrentLimit => (int) microamps

Available on some modules, check your module datasheet. This control gets or sets the maximum current draw for the given power rail in microamps.

Temperature (Get)

rail [ index ] . getTemperature <= (int) microcelsius

Some modules have a rail temperature measurement. This command gets the current rail temperature in microcelsius.

Enable (Get/Set)

rail [ index ] . setEnable => (unsigned char) enable
rail [ index ] . getEnable <= (unsigned char) enable

Setting Enable

Some rails can be enabled or disabled. The enable value is treated as a boolean 1 will enable the rail and 0 will disable it. Check the module datasheet to determine if this functionality if available for the given rail.

Getting Enable

If a rail can be enabled or disabled, getting the Enable setting will return a 1 if the rail is enabled or 0 otherwise.

Voltage (Get/Set)

rail [ index ] . setVoltage => (int) microvolts
rail [ index ] . getVoltage <= (int) microvolts

Some rails are variable voltage rails, and users can set the rails to supply voltage at range of voltage values. Check the module datasheet for the rail voltage limits, and settings.

Setting Rail Voltage

Setting this value will cause the rail to supply the requested voltage, if it is within the settings defined in the datasheet.

Getting Rail Voltage

Getting this value will return the current voltage setpoint for the rail in microvolts. If the given rail is fixed, it returns the fixed voltage setting for the given rail.

Kelvin Sensing (Get/Set)

rail [ index ] . setKelvinSensingEnable => (unsigned char) enable
rail [ index ] . getKelvinSensingEnable <= (unsigned char) enable

Some rails have kelvin sensing capabilities. See the module datasheet for more information about using kelvin sensing in your application.

Setting Kelvin Sensing mode

Setting this value to 1 will enable Kelvin sensing on this rail.

Getting Kelvin Sensing mode

Getting this value will return whether kelvin sensing is enabled on the rail. 1 is enabled 0 is disabled.

Kelvin Sensing State (Get)

rail [ index ] . getKelvinSensingState <= (unsigned char) state

When a rail is capable of Kelvin sensing, under certain error conditions kelvin sensing may be disabled by the system. This command returns the current kelvin sensing state of the rail, either enabled or disabled.

Operational Mode (Get/Set)

rail [ index ] . setOperationalMode => (unsigned char) mode
rail [ index ] . getOperationalMode <= (unsigned char) mode

Certain modules have multiple power regulation stages that can affect the behavior of the supplied rail voltage and current. This command sets and gets the preferred mode of operation for the given rail. Check the module datasheet for details on the capabilities and behavior of these operational modes.

Operational State (Get)

rail [ index ] . getOperationalState <= (unsigned char) mode

When a rail is capable of multiple operational modes, getting this value will return the current operational state of the rail, this can indicate error conditions, or a certain operational mode if the rail is in an automatic behavior.

Code Examples

C++

// All commands return aErr values when errors are encountered and aErrNone on
// success. Get commands fill the variable with the returned value.

stem.rail[0].getCurrent(microamps);
stem.rail[0].setCurrentLimit(limit);
stem.rail[0].getCurrentLimit(limit);
stem.rail[0].getTemperature(microcelsius);
stem.rail[0].setEnable(1); //enables rail.
stem.rail[0].getEnable(bEnable);
stem.rail[1].setVoltage(2000000); // set rail to 2 volts.
stem.rail[1].getVoltage(microvolts);
stem.rail[0].setKelvinSensingEnable(1); // enable kelvin sensing.
stem.rail[0].getKelvinSensingEnable(bEnabled);
stem.rail[0].getKelvinSensingState(bEnabled);
stem.rail[0].setOperationalMode(auto);
stem.rail[0].getOperationalMode(mode);
stem.rail[0].getOperationalState(state);

Reflex

// Get commands fill the variable with the returned value.

stem.rail[0].getCurrent(microamps);
stem.rail[0].setCurrentLimit(limit);
stem.rail[0].getCurrentLimit(limit);
stem.rail[0].getTemperature(microcelsius);
stem.rail[0].setEnable(1); //enables rail.
stem.rail[0].getEnable(bEnable);
stem.rail[1].setVoltage(2000000); // set rail to 2 volts.
stem.rail[1].getVoltage(microvolts);
stem.rail[0].setKelvinSensingEnable(1); // enable kelvin sensing.
stem.rail[0].getKelvinSensingEnable(bEnabled);
stem.rail[0].getKelvinSensingState(bEnabled);
stem.rail[0].setOperationalMode(auto);
stem.rail[0].getOperationalMode(mode);
stem.rail[0].getOperationalState(state);

Python

microamps = stem.rail[0].getCurrent()
print microamps.value
stem.rail[0].setCurrentLimit(limit)
limit = stem.rail[0].getCurrentLimit()
print limit.value
temperature = stem.rail[0].getTemperature()
print temperature.value
stem.rail[0].setEnable(1) //enables rail.
bEnable = stem.rail[0].getEnable()
print bEnable.value
stem.rail[0].setVoltage(2000000) // set rail to 2 volts.
microvolts = stem.rail[0].getVoltage(microvolts)
print microvolts.value
stem.rail[0].setKelvinSensingEnable() // enable kelvin sensing.
bEnabled = stem.rail[0].getKelvinSensingEnable()
print bEnabled.value
bEnabled = stem.rail[0].getKelvinSensingState()
print bEnabled.value
stem.rail[0].setOperationalMode(0, auto);
mode = stem.rail[0].getOperationalMode(0);
print mode.value
state = stem.rail[0].getOperationalState(0);
print state.value