Difference between revisions of "SW Service/API/SUSI4.0 USER MANUAL"

Revision as of 10:48, 28 October 2016

1 Introduction
2 SUSI Definition

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 I²C

I²C is a bi-directional two wire bus that was developed by Philips for use in their televisions in the 1980s. Today, I²C is used in all types of embedded systems. The I²C API allows a developer to interface a platform to a downstream embedded system environment and transfer serial messages using the I²C 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.

2.2 ID

#define SUSI_ID_UNKNOWN					0xFFFFFFFF

Description

Undefined/Unknown ID

#define SUSI_ID_BOARD_MANUFACTURER_STR				0
#define SUSI_ID_BOARD_NAME_STR					1
#define SUSI_ID_BOARD_REVISION_STR				2
#define SUSI_ID_BOARD_SERIAL_STR				3
#define SUSI_ID_BOARD_BIOS_REVISION_STR			4
#define SUSI_ID_BOARD_HW_REVISION_STR				5
#define SUSI_ID_BOARD_PLATFORM_TYPE_STR			6

Description

Board information string ID, use in SusiBoardGetStringA.

#define SUSI_ID_GET_SPEC_VERSION&nbsp				0x00000000
#define SUSI_ID_BOARD_BOOT_COUNTER_VAL				0x00000001
#define SUSI_ID_BOARD_RUNNING_TIME_METER_VAL			0x00000002
#define SUSI_ID_BOARD_PNPID_VAL				0x00000003
#define SUSI_ID_BOARD_PLATFORM_REV_VAL				0x00000004
#define SUSI_ID_BOARD_DRIVER_VERSION_VAL			0x00010000
#define SUSI_ID_BOARD_LIB_VERSION_VAL				0x00010001
#define SUSI_ID_BOARD_FIRMWARE_VERSION_VAL			0x00010002

Description

Board information value ID, use in SusiBoardGetValue.

@@ Line 145: / Line 145: @@
 &nbsp;
-  #define SUSI_STATUS_NOT_INITIALIZED				0xFFFFFFFF
+  #define SUSI_STATUS_NOT_INITIALIZED					&nbsp;&nbsp; &nbsp;0xFFFFFFFF
 :Description
@@ Line 157: / Line 157: @@
-  #define SUSI_STATUS_INITIALIZED				0xFFFFFFFE
+  #define SUSI_STATUS_INITIALIZED						&nbsp;&nbsp; &nbsp;0xFFFFFFFE
 :Description
@@ Line 169: / Line 169: @@
-  #define SUSI_STATUS_ALLOC_ERROR				0xFFFFFFFD
+  #define SUSI_STATUS_ALLOC_ERROR						&nbsp;&nbsp; &nbsp;0xFFFFFFFD
 :Description
@@ Line 181: / Line 181: @@
-  #define SUSI_STATUS_DRIVER_TIMEOUT				0xFFFFFFFC
+  #define SUSI_STATUS_DRIVER_TIMEOUT						0xFFFFFFFC
 :Description
@@ Line 193: / Line 193: @@
-  #define SUSI_STATUS_INVALID_PARAMETER				0xFFFFFEFF
+  #define SUSI_STATUS_INVALID_PARAMETER					0xFFFFFEFF
 :Description
@@ Line 217: / Line 217: @@
-  #define SUSI_STATUS_INVALID_BLOCK_LENGTH			0xFFFFFEFD
+  #define SUSI_STATUS_INVALID_BLOCK_LENGTH				0xFFFFFEFD
 :Description
@@ Line 229: / Line 229: @@
-  #define SUSI_STATUS_INVALID_DIRECTION				0xFFFFFEFC
+  #define SUSI_STATUS_INVALID_DIRECTION					0xFFFFFEFC
 :Description
@@ Line 241: / Line 241: @@
-  #define SUSI_STATUS_INVALID_BITMASK				0xFFFFFEFB
+  #define SUSI_STATUS_INVALID_BITMASK					0xFFFFFEFB
 :Description
@@ Line 253: / Line 253: @@
-  #define SUSI_STATUS_RUNNING					0xFFFFFEFA
+  #define SUSI_STATUS_RUNNING							0xFFFFFEFA
 :Description
@@ Line 265: / Line 265: @@
-  #define SUSI_STATUS_UNSUPPORTED				0xFFFFFCFF
+  #define SUSI_STATUS_UNSUPPORTED						0xFFFFFCFF
 :Description
@@ Line 275: / Line 275: @@
 ::None.
-  #define SUSI_STATUS_NOT_FOUND					0xFFFFFBFF
+  #define SUSI_STATUS_NOT_FOUND							0xFFFFFBFF
 :Description
@@ Line 287: / Line 287: @@
-  #define SUSI_STATUS_TIMEOUT					0xFFFFFBFE
+  #define SUSI_STATUS_TIMEOUT							0xFFFFFBFE
 :Description
@@ Line 299: / Line 299: @@
-  #define SUSI_STATUS_BUSY_COLLISION				0xFFFFFBFD
+  #define SUSI_STATUS_BUSY_COLLISION						0xFFFFFBFD
 :Description
@@ Line 311: / Line 311: @@
-  #define SUSI_STATUS_READ_ERROR					0xFFFFFAFF
+  #define SUSI_STATUS_READ_ERROR							0xFFFFFAFF
 :Description
@@ Line 323: / Line 323: @@
-  #define SUSI_STATUS_WRITE_ERROR				0xFFFFFAFE
+  #define SUSI_STATUS_WRITE_ERROR						0xFFFFFAFE
 :Description
@@ Line 335: / Line 335: @@
-  #define SUSI_STATUS_MORE_DATA					0xFFFFF9FF
+  #define SUSI_STATUS_MORE_DATA							0xFFFFF9FF
 :Description
@@ Line 347: / Line 347: @@
-  #define SUSI_STATUS_ERROR					0xFFFFF0FF
+  #define SUSI_STATUS_ERROR								0xFFFFF0FF
 :Description

Difference between revisions of "SW Service/API/SUSI4.0 USER MANUAL"

Revision as of 10:48, 28 October 2016

1.1 Functions

1.1.1 GPIO

1.1.2 SMBus

1.1.3 I²C

1.1.4 Watchdog

1.1.5 Hardware Monitor

1.1.6 Backlight Control

1.1.7 Storage

1.1.8 Thermal Protection

1.2 Benefits

1.3 Environment Requirements

1.3.1Operating Systems

2.1 Status Codes

2.2 ID

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools

Difference between revisions of "SW Service/API/SUSI4.0 USER MANUAL"

Revision as of 10:48, 28 October 2016

1.1 Functions

1.1.1 GPIO

1.1.2 SMBus

1.1.3 I2C

1.1.4 Watchdog

1.1.5 Hardware Monitor

1.1.6 Backlight Control

1.1.7 Storage

1.1.8 Thermal Protection

1.2 Benefits

1.3 Environment Requirements

1.3.1Operating Systems

2.1 Status Codes

2.2 ID

Navigation menu

Search

1.1.3 I²C