System Entity¶

group SystemEntity: SystemClass: The System class provides access to the core settings, configuration and system information of the BrainStem module. The class provides access to the model type, serial number and other static information as well as the ability to set boot reflexes, toggle the user LED, as well as affect module and router addresses etc.

void system_getModule(unsigned int *id, struct Result *result, const int index)¶

Get the current address the module uses on the BrainStem network.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The address the module is using on the BrainStem network.
index – The index of the entity in question.

void system_getModuleBaseAddress(unsigned int *id, struct Result *result, const int index)¶

Get the base address of the module. Software offsets and hardware offsets are added to this base address to produce the effective module address.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The address the module is using on the BrainStem network.
index – The index of the entity in question.

void system_setRouter(unsigned int *id, struct Result *result, const int index, const unsigned char address)¶

Set the router address the module uses to communicate with the host and heartbeat to in order to establish the BrainStem network. This setting must be saved and the board reset before the setting becomes active. Warning: changing the router address may cause the module to “drop off” the BrainStem network if the new router address is not in use by a BrainStem module. Please review the BrainStem network fundamentals before modifying the router address.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
address – The router address to be used.

void system_getRouter(unsigned int *id, struct Result *result, const int index)¶

Get the router address the module uses to communicate with the host and heartbeat to in order to establish the BrainStem network.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The address.
index – The index of the entity in question.

void system_setHBInterval(unsigned int *id, struct Result *result, const int index, const unsigned char interval)¶

Set the delay between heartbeat packets which are sent from the module. For link modules, these these heartbeat are sent to the host. For non-link modules, these heartbeats are sent to the router address. Interval values are in 25.6 millisecond increments Valid values are 1-255; default is 10 (256 milliseconds).

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
interval – The desired heartbeat delay.

void system_getHBInterval(unsigned int *id, struct Result *result, const int index)¶

Get the delay between heartbeat packets which are sent from the module. For link modules, these these heartbeat are sent to the host. For non-link modules, these heartbeats are sent to the router address. Interval values are in 25.6 millisecond increments.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The current heartbeat delay.
index – The index of the entity in question.

void system_setLED(unsigned int *id, struct Result *result, const int index, const unsigned char bOn)¶

Set the system LED state. Most modules have a blue system LED. Refer to the module datasheet for details on the system LED location and color.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
bOn – true: turn the LED on, false: turn LED off.

void system_getLED(unsigned int *id, struct Result *result, const int index)¶

Get the system LED state. Most modules have a blue system LED. Refer to the module datasheet for details on the system LED location and color.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. true: LED on, false: LED off.
index – The index of the entity in question.

void system_setLEDMaxBrightness(unsigned int *id, struct Result *result, const int index, const unsigned char brightness)¶

Sets the scaling factor for the brightness of all LEDs on the system. The brightness is set to the ratio of this value compared to 255 (maximum). The colors of each LED may be inconsistent at low brightness levels. Note that if the brightness is set to zero and the settings are saved, then the LEDs will no longer indicate whether the system is powered on. When troubleshooting, the user configuration may need to be manually reset in order to view the LEDs again.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
brightness – Brightness value relative to 255

void system_getLEDMaxBrightness(unsigned int *id, struct Result *result, const int index)¶

Gets the scaling factor for the brightness of all LEDs on the system. The brightness is set to the ratio of this value compared to 255 (maximum).

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Brightness value relative to 255
index – The index of the entity in question.

void system_setBootSlot(unsigned int *id, struct Result *result, const int index, const unsigned char slot)¶

Set a store slot to be mapped when the module boots. The boot slot will be mapped after the module boots from powers up, receives a reset signal on its reset input, or is issued a software reset command. Set the slot to 255 to disable mapping on boot.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
slot – The slot number in aSTORE_INTERNAL to be marked as a boot slot.

void system_getBootSlot(unsigned int *id, struct Result *result, const int index)¶

Get the store slot which is mapped when the module boots.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The slot number in aSTORE_INTERNAL that is mapped after the module boots.
index – The index of the entity in question.

void system_getVersion(unsigned int *id, struct Result *result, const int index)¶

Get the modules firmware version number. The version number is packed into the return value. Utility functions in the aVersion module can unpack the major, minor and patch numbers from the version number which looks like M.m.p.

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The build version date code.
index – The index of the entity in question.

void system_getBuild(unsigned int *id, struct Result *result, const int index)¶

Get the modules firmware build number The build number is a unique hash assigned to a specific firmware.

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Variable to be filled with build.
index – The index of the entity in question.

void system_getModel(unsigned int *id, struct Result *result, const int index)¶

Get the module’s model enumeration. A subset of the possible model enumerations is defined in BrainStem.h under “BrainStem model codes”. Other codes are be used by Acroname for proprietary module types.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The module’s model enumeration.
index – The index of the entity in question.

void system_getHardwareVersion(unsigned int *id, struct Result *result, const int index)¶

Get the module’s hardware revision information. The content of the hardware version is specific to each Acroname product and used to indicate behavioral differences between product revisions. The codes are not well defined and may change at any time.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The module’s hardware version information.
index – The index of the entity in question.

void system_getSerialNumber(unsigned int *id, struct Result *result, const int index)¶

Get the module’s serial number. The serial number is a unique 32bit integer which is usually communicated in hexadecimal format.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The module’s serial number.
index – The index of the entity in question.

void system_save(unsigned int *id, struct Result *result, const int index)¶

Save the system operating parameters to the persistent module flash memory. Operating parameters stored in the system flash will be loaded after the module reboots. Operating parameters include: heartbeat interval, module address, module router address

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.

void system_reset(unsigned int *id, struct Result *result, const int index)¶

Reset the system. aErrTimeout indicates a successful reset, as the system resets immediately, which tears down the USB-link immediately, thus preventing an affirmative response.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.

void system_logEvents(unsigned int *id, struct Result *result, const int index)¶

Saves system log events to a slot defined by the module (usually ram slot 0).

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.

void system_getUptime(unsigned int *id, struct Result *result, const int index)¶

Get the module’s accumulated uptime in minutes

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The module’s accumulated uptime in minutes.
index – The index of the entity in question.

void system_getTemperature(unsigned int *id, struct Result *result, const int index)¶

Get the module’s current temperature in micro-C

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The module’s system temperature in micro-C
index – The index of the entity in question.

void system_getMinimumTemperature(unsigned int *id, struct Result *result, const int index)¶

Get the module’s minimum temperature ever recorded in micro-C (uC) This value will persists through a power cycle.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The module’s minimum system temperature in micro-C
index – The index of the entity in question.

void system_getMaximumTemperature(unsigned int *id, struct Result *result, const int index)¶

Get the module’s maximum temperature ever recorded in micro-C (uC) This value will persists through a power cycle.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The module’s maximum system temperature in micro-C
index – The index of the entity in question.

void system_getInputVoltage(unsigned int *id, struct Result *result, const int index)¶

Get the module’s input voltage.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The module’s input voltage reported in microvolts.
index – The index of the entity in question.

void system_getInputCurrent(unsigned int *id, struct Result *result, const int index)¶

Get the module’s input current.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The module’s input current reported in microamps.
index – The index of the entity in question.

void system_getModuleHardwareOffset(unsigned int *id, struct Result *result, const int index)¶

Get the module hardware address offset. This is added to the base address to allow the module address to be configured in hardware. Not all modules support the hardware module address offset. Refer to the module datasheet.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The module address offset.
index – The index of the entity in question.

void system_setModuleSoftwareOffset(unsigned int *id, struct Result *result, const int index, const unsigned char address)¶

Set the software address offset. This software offset is added to the module base address, and potentially a module hardware address to produce the final module address. You must save the system settings and restart for this to take effect. Please review the BrainStem network fundamentals before modifying the module address.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
address – The address for the module. Value must be even from 0-254.

void system_getModuleSoftwareOffset(unsigned int *id, struct Result *result, const int index)¶

Get the software address offset. This software offset is added to the module base address, and potentially a module hardware address to produce the final module address. You must save the system settings and restart for this to take effect. Please review the BrainStem network fundamentals before modifying the module address.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The address for the module. Value must be even from 0-254.
index – The index of the entity in question.

void system_getRouterAddressSetting(unsigned int *id, struct Result *result, const int index)¶

Get the router address system setting. This setting may not be the same as the current router address if the router setting was set and saved but no reset has occurred. Please review the BrainStem network fundamentals before modifying the module address.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The address for the module. Value must be even from 0-254.
index – The index of the entity in question.

void system_routeToMe(unsigned int *id, struct Result *result, const int index, const unsigned char bOn)¶

Enables/Disables the route to me function. This function allows for easy networking of BrainStem modules. Enabling (1) this function will send an I2C General Call to all devices on the network and request that they change their router address to the of the calling device. Disabling (0) will cause all devices on the BrainStem network to revert to their default address.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
bOn – Enable or disable of the route to me function 1 = enable.

void system_getPowerLimit(unsigned int *id, struct Result *result, const int index)¶

Reports the amount of power the system has access to and thus how much power can be budgeted to sinking devices.

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. The available power in milli-Watts (mW, 1 t)
index – The index of the entity in question.

void system_getPowerLimitMax(unsigned int *id, struct Result *result, const int index)¶

Gets the user defined maximum power limit for the system. Provides mechanism for defining an unregulated power supplies capability.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Variable to be filled with the power limit in milli-Watts (mW)
index – The index of the entity in question.

void system_setPowerLimitMax(unsigned int *id, struct Result *result, const int index, const unsigned int power)¶

Sets a user defined maximum power limit for the system. Provides mechanism for defining an unregulated power supplies capability.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
power – Limit in milli-Watts (mW) to be set.

void system_getPowerLimitState(unsigned int *id, struct Result *result, const int index)¶

Gets a bit mapped representation of the factors contributing to the power limit. Active limit can be found through PowerDeliverClass::getPowerLimit().

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Variable to be filled with the state.
index – The index of the entity in question.

void system_getUnregulatedVoltage(unsigned int *id, struct Result *result, const int index)¶

Gets the voltage present at the unregulated port.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Variable to be filled with the voltage in micro-Volts (uV).
index – The index of the entity in question.

void system_getUnregulatedCurrent(unsigned int *id, struct Result *result, const int index)¶

Gets the current passing through the unregulated port.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Variable to be filled with the current in micro-Amps (uA).
index – The index of the entity in question.

void system_getInputPowerSource(unsigned int *id, struct Result *result, const int index)¶

Provides the source of the current power source in use.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Variable to be filled with enumerated representation of the source.
index – The index of the entity in question.

void system_getInputPowerBehavior(unsigned int *id, struct Result *result, const int index)¶

Gets the systems input power behavior. This behavior refers to where the device sources its power from and what happens if that power source goes away.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Variable to be filled with an enumerated value representing behavior.
index – The index of the entity in question.

void system_setInputPowerBehavior(unsigned int *id, struct Result *result, const int index, const unsigned char behavior)¶

Sets the systems input power behavior. This behavior refers to where the device sources its power from and what happens if that power source goes away.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
behavior – An enumerated representation of behavior to be set.

void system_getInputPowerBehaviorConfig(unsigned int *id, struct Result *result, const int index, unsigned int *buffer, const unsigned int bufferLength)¶

Gets the input power behavior configuration Certain behaviors use a list of ports to determine priority when budgeting power.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Length that was actually received and filled.
index – The index of the entity in question.
buffer – pointer to the start of a c style buffer to be filled
bufferLength – Length of the buffer to be filed

void system_setInputPowerBehaviorConfig(unsigned int *id, struct Result *result, const int index, unsigned int *buffer, const unsigned int bufferLength)¶

Sets the input power behavior configuration Certain behaviors use a list of ports to determine priority when budgeting power.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
buffer – Pointer to the start of a c style buffer to be transferred.
bufferLength – Length of the buffer to be transferred.

void system_getName(unsigned int *id, struct Result *result, const int index, unsigned char *buffer, const unsigned int bufferLength)¶

Gets a user defined name of the device. Helpful for identifying ports/devices in a static environment.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Length that was actually received and filled.
index – The index of the entity in question.
buffer – pointer to the start of a c style buffer to be filled
bufferLength – Length of the buffer to be filed

void system_setName(unsigned int *id, struct Result *result, const int index, unsigned char *buffer, const unsigned int bufferLength)¶

Sets a user defined name for the device. Helpful for identification when multiple devices of the same type are present in a system.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
buffer – Pointer to the start of a c style buffer to be transferred.
bufferLength – Length of the buffer to be transferred.

void system_resetEntityToFactoryDefaults(unsigned int *id, struct Result *result, const int index)¶

Resets the SystemClass Entity to it factory default configuration.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.

void system_resetDeviceToFactoryDefaults(unsigned int *id, struct Result *result, const int index)¶

Resets the device to it factory default configuration.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.

void system_getLinkInterface(unsigned int *id, struct Result *result, const int index)¶

Gets the link interface configuration. This refers to which interface is being used for control by the device.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Variable to be filled with an enumerated value representing interface.
- 0 = Auto= systemLinkAuto
- 1 = Control Port = systemLinkUSBControl
- 2 = Hub Upstream Port = systemLinkUSBHub
index – The index of the entity in question.

void system_setLinkInterface(unsigned int *id, struct Result *result, const int index, const unsigned char linkInterface)¶

Sets the link interface configuration. This refers to which interface is being used for control by the device.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone on success. Non-zero error code on failure.
index – The index of the entity in question.
linkInterface – An enumerated representation of interface to be set.
- 0 = Auto= systemLinkAuto
- 1 = Control Port = systemLinkUSBControl
- 2 = Hub Upstream Port = systemLinkUSBHub

void system_getErrors(unsigned int *id, struct Result *result, const int index)¶

Gets any system level errors. Calling this function will clear the current errors. If the error persists it will be set again.

Returns common entity return values

Parameters:

id – ID assigned through “module_createStem”
result – Object containing aErrNone and the requested value on success. Non-zero error code on failure. Bit mapped field representing the devices errors
index – The index of the entity in question.