Difference between revisions of "SW Service/API/SUSI4.0 USER MANUAL"
From ESS-WIKI
Weichih.lin (talk | contribs) |
Weichih.lin (talk | contribs) |
||
| Line 9: | Line 9: | ||
SUSI provides not only the underlying drivers required but also a rich set of user-friendly, intelligent and integrated interfaces, which speeds development, enhances security and offers add-on value for Advantech platforms. SUSI plays the role of catalyst between developer and solution, and makes Advantech embedded platforms easier and simpler to adopt and operate with customer applications. | SUSI provides not only the underlying drivers required but also a rich set of user-friendly, intelligent and integrated interfaces, which speeds development, enhances security and offers add-on value for Advantech platforms. SUSI plays the role of catalyst between developer and solution, and makes Advantech embedded platforms easier and simpler to adopt and operate with customer applications. | ||
| − | |||
== 1.1 Functions == | == 1.1 Functions == | ||
| Line 18: | Line 17: | ||
General Purpose Input/Output is a flexible parallel interface that allows a variety of custom connections. It supports various Digital I/O devices – input devices like buttons, switches; output devices such as cash drawers, LED lights…etc. And, allows users to monitor the level of signal input or set the output status to switch on/off the device. Our APIs also provided Programmable GPIO and allows developers to dynamically set the GPIO input or output status. | General Purpose Input/Output is a flexible parallel interface that allows a variety of custom connections. It supports various Digital I/O devices – input devices like buttons, switches; output devices such as cash drawers, LED lights…etc. And, allows users to monitor the level of signal input or set the output status to switch on/off the device. Our APIs also provided Programmable GPIO and allows developers to dynamically set the GPIO input or output status. | ||
| − | |||
| Line 33: | Line 31: | ||
I<sup>2</sup>C is a bi-directional two wire bus that was developed by Philips for use in their televisions in the 1980s. Today, I<sup>2</sup>C is used in all types of embedded systems. The I<sup>2</sup>C API allows a developer to interface a platform to a downstream embedded system environment and transfer serial messages using the I<sup>2</sup>C protocols, allowing multiple simultaneous device control. | I<sup>2</sup>C is a bi-directional two wire bus that was developed by Philips for use in their televisions in the 1980s. Today, I<sup>2</sup>C is used in all types of embedded systems. The I<sup>2</sup>C API allows a developer to interface a platform to a downstream embedded system environment and transfer serial messages using the I<sup>2</sup>C protocols, allowing multiple simultaneous device control. | ||
| − | |||
=== 1.1.4 Watchdog === | === 1.1.4 Watchdog === | ||
| Line 42: | Line 39: | ||
A watchdog timer can be programmed to perform a warm boot (restarting the system) after a certain number of seconds during which a program or computer fails to respond following the most recent mouse click or keyboard action. | A watchdog timer can be programmed to perform a warm boot (restarting the system) after a certain number of seconds during which a program or computer fails to respond following the most recent mouse click or keyboard action. | ||
| − | |||
| Line 51: | Line 47: | ||
The Hardware Monitor (HWM) APIs is a system health supervision API that inspects certain condition indexes, such as smart fan, fan speed, temperature, current, case open and voltage. | The Hardware Monitor (HWM) APIs is a system health supervision API that inspects certain condition indexes, such as smart fan, fan speed, temperature, current, case open and voltage. | ||
| − | |||
=== 1.1.6 Backlight Control === | === 1.1.6 Backlight Control === | ||
| Line 59: | Line 54: | ||
The Backlight Control APIs allows a developer to interface platform to easily control brightness through PWM and backlight on/off. | The Backlight Control APIs allows a developer to interface platform to easily control brightness through PWM and backlight on/off. | ||
| − | |||
=== 1.1.7 Storage === | === 1.1.7 Storage === | ||
| Line 67: | Line 61: | ||
Storage is a non-volatile storage, the storage APIs allows a developer to access storage information, read/write data to storage and lock/unlock data area (same like write protection) by a key. | Storage is a non-volatile storage, the storage APIs allows a developer to access storage information, read/write data to storage and lock/unlock data area (same like write protection) by a key. | ||
| − | |||
=== 1.1.8 Thermal Protection === | === 1.1.8 Thermal Protection === | ||
| Line 81: | Line 74: | ||
*'''Faster Time to Market''' | *'''Faster Time to Market''' | ||
| − | SUSI's unified API helps developers write applications to control the hardware without knowing the hardware specs of the chipsets and driver architecture. | + | :SUSI's unified API helps developers write applications to control the hardware without knowing the hardware specs of the chipsets and driver architecture. |
| − | |||
*'''Reduced Project Effort''' | *'''Reduced Project Effort''' | ||
| − | When customers have their own devices connected to the onboard bus, they can either: study the data sheet and write the driver & API from scratch, or they can use SUSI to start the integration with a 50% head start. Developers can reference the sample program on the CD to see and learn more about the software development environment. | + | :When customers have their own devices connected to the onboard bus, they can either: study the data sheet and write the driver & API from scratch, or they can use SUSI to start the integration with a 50% head start. Developers can reference the sample program on the CD to see and learn more about the software development environment. |
| − | |||
*'''Enhances Hardware Platform Reliability''' | *'''Enhances Hardware Platform Reliability''' | ||
| − | SUSI provides a trusted custom ready solution which combines chipset and library function support, controlling application development through SUSI enhances reliability and brings peace of mind. | + | :SUSI provides a trusted custom ready solution which combines chipset and library function support, controlling application development through SUSI enhances reliability and brings peace of mind.:::: |
| − | |||
*'''Flexible Upgrade Possibilities''' | *'''Flexible Upgrade Possibilities''' | ||
| − | SUSI supports an easy upgrade solution for customers. Customers just need to install the new version SUSI that supports the new functions. | + | :SUSI supports an easy upgrade solution for customers. Customers just need to install the new version SUSI that supports the new functions. |
| − | |||
*'''Backward compatibility''' | *'''Backward compatibility''' | ||
| − | Support SUSI 3.0, iManager 2.0 and EAPI 1.0 interface. Customers don’t need to change any APIs in their applications. | + | :Support SUSI 3.0, iManager 2.0 and EAPI 1.0 interface. Customers don’t need to change any APIs in their applications. |
| Line 113: | Line 102: | ||
=== 1.3.1Operating Systems === | === 1.3.1Operating Systems === | ||
| − | Windows XP Embedded | + | ::Windows XP Embedded |
| − | Windows XP 32-bit | + | ::Windows XP 32-bit |
| − | Windows 7 (x86 / x64) | + | ::Windows 7 (x86 / x64) |
| − | WES7 (x86 / x64) | + | ::WES7 (x86 / x64) |
| − | Windows 8 Desktop (x86 / x64) | + | ::Windows 8 Desktop (x86 / x64) |
| − | Windows CE 5 / 6 / 7 | + | ::Windows CE 5 / 6 / 7 |
| − | Linux (Project based, request from your local FAE) | + | ::Linux (Project based, request from your local FAE) |
| − | Android (Project based, request from your local FAE) | + | ::Android (Project based, request from your local FAE) |
| − | QNX | + | ::QNX (Project based, request from your local FAE) |
| − | |||
| − | |||
| + | ::VxWorks (Project based, request from your local FAE) | ||
| + | | ||
= 2 SUSI Definition = | = 2 SUSI Definition = | ||
| Line 147: | Line 136: | ||
#define SUSI_STATUS_NOT_INITIALIZED 0xFFFFFFFF | #define SUSI_STATUS_NOT_INITIALIZED 0xFFFFFFFF | ||
| − | Description | + | :Description |
| − | The SUSI API library is not yet or unsuccessfully initialized. SusiLibInitialize needs to be called prior to the first access of any other SUSI API functions. | + | ::The SUSI API library is not yet or unsuccessfully initialized. SusiLibInitialize needs to be called prior to the first access of any other SUSI API functions. |
| − | Actions | + | :Actions |
| − | Call SusiLibInitialize. | + | ::Call SusiLibInitialize. |
| − | |||
#define SUSI_STATUS_INITIALIZED 0xFFFFFFFE | #define SUSI_STATUS_INITIALIZED 0xFFFFFFFE | ||
| − | Description | + | :Description |
| − | Library is initialized. | + | ::Library is initialized. |
| − | Actions | + | :Actions |
| − | None. | + | :None. |
| + | #define SUSI_STATUS_ALLOC_ERROR 0xFFFFFFFD | ||
| − | + | :Description | |
| − | + | ::Memory Allocation Error. | |
| − | + | :Actions | |
| − | + | ::Free memory and try again. | |
| − | |||
| − | |||
#define SUSI_STATUS_DRIVER_TIMEOUT 0xFFFFFFFC | #define SUSI_STATUS_DRIVER_TIMEOUT 0xFFFFFFFC | ||
| − | Description | + | :Description |
| − | Time out in driver. This is Normally caused by hardware/software semaphore timeout. | + | ::Time out in driver. This is Normally caused by hardware/software semaphore timeout. |
| − | Actions | + | :Actions |
| − | Retry. | + | ::Retry. |
| − | |||
#define SUSI_STATUS_INVALID_PARAMETER 0xFFFFFEFF | #define SUSI_STATUS_INVALID_PARAMETER 0xFFFFFEFF | ||
| − | Description | + | :Description |
| − | |||
| − | |||
| − | + | ::One or more of the SUSI API functions call parameters are out of defined range. | |
| − | + | :Actions | |
| + | ::Verify Function Parameters. | ||
#define SUSI_STATUS_INVALID_BLOCK_ALIGNMENT 0xFFFFFEFE | #define SUSI_STATUS_INVALID_BLOCK_ALIGNMENT 0xFFFFFEFE | ||
| − | Description | + | :Description |
| − | The Block Alignment is incorrect. | + | ::The Block Alignment is incorrect. |
| − | Actions | + | :Actions |
| − | Use Inputs and Outputs to correctly select input and outputs. | + | ::Use Inputs and Outputs to correctly select input and outputs. |
| − | |||
#define SUSI_STATUS_INVALID_BLOCK_LENGTH 0xFFFFFEFD | #define SUSI_STATUS_INVALID_BLOCK_LENGTH 0xFFFFFEFD | ||
| − | Description | + | :Description |
| − | This means that the Block length is too long. | + | ::This means that the Block length is too long. |
| − | Actions | + | :Actions |
| − | Use Alignment Capabilities information to correctly align write access. | + | ::Use Alignment Capabilities information to correctly align write access. |
| − | |||
#define SUSI_STATUS_INVALID_DIRECTION 0xFFFFFEFC | #define SUSI_STATUS_INVALID_DIRECTION 0xFFFFFEFC | ||
| − | Description | + | :Description |
| − | The current Direction Argument attempts to set GPIOs to a unsupported direction. I.E. Setting GPI to Output. | + | ::The current Direction Argument attempts to set GPIOs to a unsupported direction. I.E. Setting GPI to Output. |
| − | Actions | + | :Actions |
| − | Use Inputs and Outputs to correctly select input and outputs. | + | ::Use Inputs and Outputs to correctly select input and outputs. |
| − | |||
#define SUSI_STATUS_INVALID_BITMASK 0xFFFFFEFB | #define SUSI_STATUS_INVALID_BITMASK 0xFFFFFEFB | ||
| − | Description | + | :Description |
| − | The Bitmask Selects bits/GPIOs which are not supported for the current ID. | + | ::The Bitmask Selects bits/GPIOs which are not supported for the current ID. |
| − | Actions | + | :Actions |
| − | Use Inputs and Outputs to probe supported bits. | + | ::Use Inputs and Outputs to probe supported bits. |
| − | |||
#define SUSI_STATUS_RUNNING 0xFFFFFEFA | #define SUSI_STATUS_RUNNING 0xFFFFFEFA | ||
| − | Description | + | :Description |
| − | Watchdog timer already started. | + | ::Watchdog timer already started. |
| − | Actions | + | :Actions |
| − | Call SusiWDogStop before retrying. | + | ::Call SusiWDogStop before retrying. |
| − | |||
#define SUSI_STATUS_UNSUPPORTED 0xFFFFFCFF | #define SUSI_STATUS_UNSUPPORTED 0xFFFFFCFF | ||
| − | Description | + | :Description |
| − | This function or ID is not supported at the actual hardware environment. | + | ::This function or ID is not supported at the actual hardware environment. |
| − | Actions | + | :Actions |
| − | None. | + | ::None. |
| − | #define SUSI_STATUS_NOT_FOUND 0xFFFFFBFF | + | #define SUSI_STATUS_NOT_FOUND 0xFFFFFBFF |
| − | Description | + | :Description |
| − | Selected device was not found | + | ::Selected device was not found |
| − | Actions | + | :Actions |
| − | None. | + | ::None. |
| − | |||
| − | #define SUSI_STATUS_TIMEOUT 0xFFFFFBFE | + | #define SUSI_STATUS_TIMEOUT 0xFFFFFBFE |
| − | Description | + | :Description |
| − | Device has no response. | + | ::Device has no response. |
| − | Actions | + | :Actions |
| − | None. | + | ::None. |
| − | |||
#define SUSI_STATUS_BUSY_COLLISION 0xFFFFFBFD | #define SUSI_STATUS_BUSY_COLLISION 0xFFFFFBFD | ||
| − | Description | + | :Description |
| − | The selected device or ID is busy or a data collision is detected. | + | ::The selected device or ID is busy or a data collision is detected. |
| − | Actions | + | :Actions |
| − | Retry. | + | ::Retry. |
| − | |||
#define SUSI_STATUS_READ_ERROR 0xFFFFFAFF | #define SUSI_STATUS_READ_ERROR 0xFFFFFAFF | ||
| − | Description | + | :Description |
| − | An error is detected during a read operation. | + | ::An error is detected during a read operation. |
| − | Actions | + | :Actions |
| − | Retry. | + | ::Retry. |
| − | |||
#define SUSI_STATUS_WRITE_ERROR 0xFFFFFAFE | #define SUSI_STATUS_WRITE_ERROR 0xFFFFFAFE | ||
| − | Description | + | :Description |
| − | An error is detected during a write operation. | + | ::An error is detected during a write operation. |
| − | Actions | + | :Actions |
| − | Retry. | + | ::Retry. |
| − | |||
#define SUSI_STATUS_MORE_DATA 0xFFFFF9FF | #define SUSI_STATUS_MORE_DATA 0xFFFFF9FF | ||
| − | Description | + | :Description |
| − | The amount of available data exceeds the buffer size. Storage buffer overflow was prevented. Read count was larger than the defined buffer length. | + | ::The amount of available data exceeds the buffer size. Storage buffer overflow was prevented. Read count was larger than the defined buffer length. |
| − | Actions | + | :Actions |
| − | Either increase the buffer size or reduce the block length. | + | ::Either increase the buffer size or reduce the block length. |
| − | |||
#define SUSI_STATUS_ERROR 0xFFFFF0FF | #define SUSI_STATUS_ERROR 0xFFFFF0FF | ||
| − | Description | + | :Description |
| − | Generic error message. No further error details are available. | + | ::Generic error message. No further error details are available. |
| − | Actions | + | :Actions |
| − | None. | + | ::None. |
| − | |||
#define SUSI_STATUS_SUCCESS 0 | #define SUSI_STATUS_SUCCESS 0 | ||
| − | Description | + | :Description |
| − | The operation is successful. | + | ::The operation is successful. |
| − | Actions | + | :Actions |
| − | None. | + | ::None. |
<headertabs></headertabs> | <headertabs></headertabs> | ||
Revision as of 10:01, 28 October 2016
[edit]
SUSI – A Bridge to Simplify & Enhance H/W & Application Implementation Efficiency
When developers want to write an application that involves hardware access, they have to study the specifications to write the drivers. This is a time-consuming job and requires lots of expertise.
Advantech has done all the hard work for our customers with the release of a suite of Software APIs (Application Programming Interfaces), called Secured & Unified Smart Interface (SUSI).
SUSI provides not only the underlying drivers required but also a rich set of user-friendly, intelligent and integrated interfaces, which speeds development, enhances security and offers add-on value for Advantech platforms. SUSI plays the role of catalyst between developer and solution, and makes Advantech embedded platforms easier and simpler to adopt and operate with customer applications.
1.1 Functions
1.1.1 GPIO
General Purpose Input/Output is a flexible parallel interface that allows a variety of custom connections. It supports various Digital I/O devices – input devices like buttons, switches; output devices such as cash drawers, LED lights…etc. And, allows users to monitor the level of signal input or set the output status to switch on/off the device. Our APIs also provided Programmable GPIO and allows developers to dynamically set the GPIO input or output status.
1.1.2 SMBus
SMBus is the System Management Bus defined by Intel® Corporation in 1995. It is used in personal computers and servers for low-speed system management communications. Today, SMBus is used in all types of embedded systems. The SMBus APIs allows a developer to interface a platform to a downstream embedded system environment and transfer serial messages using the SMBus protocols, allowing multiple simultaneous device control.
1.1.3 I2C
I2C is a bi-directional two wire bus that was developed by Philips for use in their televisions in the 1980s. Today, I2C is used in all types of embedded systems. The I2C API allows a developer to interface a platform to a downstream embedded system environment and transfer serial messages using the I2C protocols, allowing multiple simultaneous device control.
1.1.4 Watchdog
A watchdog timer (WDT) is a device or electronic card that performs a specific operation after a certain period of time if something goes wrong with an electronic system and the system does not recover on its own.
A watchdog timer can be programmed to perform a warm boot (restarting the system) after a certain number of seconds during which a program or computer fails to respond following the most recent mouse click or keyboard action.
1.1.5 Hardware Monitor
The Hardware Monitor (HWM) APIs is a system health supervision API that inspects certain condition indexes, such as smart fan, fan speed, temperature, current, case open and voltage.
1.1.6 Backlight Control
The Backlight Control APIs allows a developer to interface platform to easily control brightness through PWM and backlight on/off.
1.1.7 Storage
Storage is a non-volatile storage, the storage APIs allows a developer to access storage information, read/write data to storage and lock/unlock data area (same like write protection) by a key.
1.1.8 Thermal Protection
Thermal Protection can select a thermal source to monitor. When source temperature reach the limit, SUSI can act protect function to protect system.
1.2 Benefits
- Faster Time to Market
- SUSI's unified API helps developers write applications to control the hardware without knowing the hardware specs of the chipsets and driver architecture.
- Reduced Project Effort
- When customers have their own devices connected to the onboard bus, they can either: study the data sheet and write the driver & API from scratch, or they can use SUSI to start the integration with a 50% head start. Developers can reference the sample program on the CD to see and learn more about the software development environment.
- Enhances Hardware Platform Reliability
- SUSI provides a trusted custom ready solution which combines chipset and library function support, controlling application development through SUSI enhances reliability and brings peace of mind.::::
- Flexible Upgrade Possibilities
- SUSI supports an easy upgrade solution for customers. Customers just need to install the new version SUSI that supports the new functions.
- Backward compatibility
- Support SUSI 3.0, iManager 2.0 and EAPI 1.0 interface. Customers don’t need to change any APIs in their applications.
1.3 Environment Requirements
1.3.1Operating Systems
- Windows XP Embedded
- Windows XP 32-bit
- Windows 7 (x86 / x64)
- WES7 (x86 / x64)
- Windows 8 Desktop (x86 / x64)
- Windows CE 5 / 6 / 7
- Linux (Project based, request from your local FAE)
- Android (Project based, request from your local FAE)
- QNX (Project based, request from your local FAE)
- VxWorks (Project based, request from your local FAE)
Susi4.h file includes the API declaration, constants and flags that are required for programming.
2.1 Status Codes
All SUSI API functions immediately return a status code from a common list of possible errors. Any function may return any of the defined status codes. See the Appendix for more detailed information.
#define SUSI_STATUS_NOT_INITIALIZED 0xFFFFFFFF
- Description
- The SUSI API library is not yet or unsuccessfully initialized. SusiLibInitialize needs to be called prior to the first access of any other SUSI API functions.
- Actions
- Call SusiLibInitialize.
#define SUSI_STATUS_INITIALIZED 0xFFFFFFFE
- Description
- Library is initialized.
- Actions
- None.
#define SUSI_STATUS_ALLOC_ERROR 0xFFFFFFFD
- Description
- Memory Allocation Error.
- Actions
- Free memory and try again.
#define SUSI_STATUS_DRIVER_TIMEOUT 0xFFFFFFFC
- Description
- Time out in driver. This is Normally caused by hardware/software semaphore timeout.
- Actions
- Retry.
#define SUSI_STATUS_INVALID_PARAMETER 0xFFFFFEFF
- Description
- One or more of the SUSI API functions call parameters are out of defined range.
- Actions
- Verify Function Parameters.
#define SUSI_STATUS_INVALID_BLOCK_ALIGNMENT 0xFFFFFEFE
- Description
- The Block Alignment is incorrect.
- Actions
- Use Inputs and Outputs to correctly select input and outputs.
#define SUSI_STATUS_INVALID_BLOCK_LENGTH 0xFFFFFEFD
- Description
- This means that the Block length is too long.
- Actions
- Use Alignment Capabilities information to correctly align write access.
#define SUSI_STATUS_INVALID_DIRECTION 0xFFFFFEFC
- Description
- The current Direction Argument attempts to set GPIOs to a unsupported direction. I.E. Setting GPI to Output.
- Actions
- Use Inputs and Outputs to correctly select input and outputs.
#define SUSI_STATUS_INVALID_BITMASK 0xFFFFFEFB
- Description
- The Bitmask Selects bits/GPIOs which are not supported for the current ID.
- Actions
- Use Inputs and Outputs to probe supported bits.
#define SUSI_STATUS_RUNNING 0xFFFFFEFA
- Description
- Watchdog timer already started.
- Actions
- Call SusiWDogStop before retrying.
#define SUSI_STATUS_UNSUPPORTED 0xFFFFFCFF
- Description
- This function or ID is not supported at the actual hardware environment.
- Actions
- None.
#define SUSI_STATUS_NOT_FOUND 0xFFFFFBFF
- Description
- Selected device was not found
- Actions
- None.
#define SUSI_STATUS_TIMEOUT 0xFFFFFBFE
- Description
- Device has no response.
- Actions
- None.
#define SUSI_STATUS_BUSY_COLLISION 0xFFFFFBFD
- Description
- The selected device or ID is busy or a data collision is detected.
- Actions
- Retry.
#define SUSI_STATUS_READ_ERROR 0xFFFFFAFF
- Description
- An error is detected during a read operation.
- Actions
- Retry.
#define SUSI_STATUS_WRITE_ERROR 0xFFFFFAFE
- Description
- An error is detected during a write operation.
- Actions
- Retry.
#define SUSI_STATUS_MORE_DATA 0xFFFFF9FF
- Description
- The amount of available data exceeds the buffer size. Storage buffer overflow was prevented. Read count was larger than the defined buffer length.
- Actions
- Either increase the buffer size or reduce the block length.
#define SUSI_STATUS_ERROR 0xFFFFF0FF
- Description
- Generic error message. No further error details are available.
- Actions
- None.
#define SUSI_STATUS_SUCCESS 0
- Description
- The operation is successful.
- Actions
- None.