2. Application Controller API Reference
T11, Version 1.01ii
Legal Notice
This documentation is owned by SkyWave Mobile Communications Inc. (SkyWave) and protected by
applicable copyright laws and international treaty provisions. Other copyrighted names used are the property
of their respective owners. Therefore, you must treat this documentation like any other copyrighted material.
You may not make the documentation, or copies thereof, available in any manner or form, or use, copy or
transfer any part, to anyone outside your company.
If you received this documentation by electronic transmission or download, by installation or use of the
documentation, you acknowledge that you have read and understand this license agreement and agree to be
bound by its terms and conditions.
This documentation is provided on an as-is basis without any warranty of any kind. You assume the entire
risk as to the results or performance of the software. Under no circumstance shall SkyWave be held liable for
any direct, indirect, consequential, or incidental damages arising from the use or inability to use the software
or documentation.
All trademarks or registered trademarks are the property of their respective owners. SkyWave reserves the
right to make changes to products and or specifications without notice.
From www.SkyWave.com login and follow the link to the downloads section. The complete Software and
Documentation License Agreement is distributed as a part of the SkyWave Developer’s Toolkit (SDK).
Contact Information
SkyWave Mobile Communications Inc.
On-line:
• Web site: www.SkyWave.com
On-line documentation:
• Login at support.skywave.com and follow the link to the downloads section
Technical Support by E-mail
• support@skywave.com.
Technical Support by Telephone
• +1 613-836-6288 (press 1 for customer support)
3. Application Controller API Reference
T11, Version 1.01iii
Table of Contents
Legal Notice ....................................................................................................................... ii
Contact Information.......................................................................................................... ii
Preface................................................................................................................................ v
Purpose v
Audience v
Notation v
Reference v
Safety Disclaimer v
Limited Liability vi
Warranty vi
1 Bus Application Controller Overview....................................................................... 1
2 Software Architecture ................................................................................................ 5
2.1 Real-Time Operating System (RTOS) 5
2.2 API 5
3 Development Environment ........................................................................................ 7
3.1 Required Development Tools 7
3.2 Required Skills/Knowledge 7
3.3 Application Controller Framework File Structure 7
4 Application Interface Prototypes............................................................................... 9
4.1 Serial Communication Access 9
4.1.1 Serial Configure 9
4.1.2 Serial Transmit Tx Busy 9
4.1.3 Serial Write 9
4.2 Terminal Controller Communication 10
4.3 Terminal Controller Mirrored Ports Access 10
4.3.1 Read Mirrored Port 10
4.3.2 Registered Mirrored Port Change Callback 11
4.4 I/O Access 11
4.4.1 Standard I/O Line Setup 11
4.4.2 Standard I/O Line Read 11
4.4.3 Standard I/O Line Write 12
4.4.4 Extended I/O Line Setup 12
4.4.5 Extended I/O Line Read 12
4.4.6 Extended I/O Line Write 13
4.5 Timer 13
4.5.1 Timer Start 13
4.5.2 Timer Stop 13
4.5.3 Timer Read 14
4.5.4 Timer Clock 14
4.6 GPS 14
4.6.1 GPS Status 14
4.6.2 GPS Power 15
4.6.3 GPS Distance 15
4.7 Terminal Controller Status & Control 15
4. Application Controller API Reference
T11, Version 1.01iv
4.7.1 Terminal Controller Power Control 15
4.7.2 Terminal Controller Power Status 16
4.8 Console 16
4.8.1 Console Output 16
4.8.2 Console Register Callback 16
4.9 Terminal Controller Messaging 17
4.9.1 Add User Message 17
4.9.2 Get User Message 17
4.9.3 Remove User Message 18
4.9.4 Set Rx Message Filter 18
4.9.5 Get Rx Message Filter 18
4.10 File Access 19
4.10.1 File Open 19
4.10.2 File Close 19
4.10.3 File Seek 19
4.10.4 File Read 20
4.11 EEPROM Access 20
4.11.1 EEPROM Read 20
4.11.2 EEPROM Write 20
4.12 Flash Access 21
4.12.1 Flash Page Read 21
4.12.2 Flash Page Write 21
4.13 ECAN Access 21
4.13.1 ECAN Configure 22
4.13.2 ECAN Transmit Tx Busy 22
4.13.3 ECAN Transmit 22
4.14 Port Access 23
4.14.1 Port Read 23
4.14.2 Port Write 23
4.15 RTOS Wrapper 23
4.15.1 RTOS Start Wrapper 23
4.15.2 RTOS Task Yield Wrapper 23
4.15.3 RTOS Task Create Wrapper 24
Appendix A Mirrored Values ..................................................................................... 25
Document Versions.......................................................................................................... 26
Index ................................................................................................................................. 27
5. Application Controller API Reference
T11, Version 1.01v
Preface
Purpose
This document describes the SureLinx 8100c onboard computer (Bus application
controller) framework, and applies only to those SureLinx terminals supporting the card.
This API framework allows Solution Providers to impalement their own custom logic.
Audience
This document is for technical readers familiar with application controller programming
and operation.
Notation
This document uses terminal to refer to the SureLinx transceiver unit and antennae and
uses terminal controller to refer to the motherboard in the transceiver unit. Bus
application controller refers to the embedded microcontroller or daughter card.
This document uses ‘satellite’ or ‘satellite service’ to refer to D+ and IsatM2M service
except when discussing information specific to a particular service (D+ only or IsatM2M
only) or a specific satellite (GPS satellite or Inmarsat satellite).
Reference
It is recommended that you be familiar with the content of the following documents
before using this guide. These documents are available from the SkyWave Developer’s
Toolkit (SDK), or support.skywave.com:
[G1] Introduction to SkyWave Products and Services
[T7] SureLinx 8100 Hardware Guide
[T8] DMR-800 and SureLinx User’s Guide
[T9] DMR-800 and SureLinx API Reference
A number of sample applications are available on the SDK.
Safety Disclaimer
SkyWave makes no warranties, representations, or guarantees that the products and
network services are suitable for any use (including without limitation marine safety and
distress systems, and life support services) in which the failure of the products or network
services could result in death or personal injury. The Solution Provider assumes all
liability associated with selling any products or network services for any such
applications, and the Solution Provider will defend, indemnify, and hold SkyWave
harmless against any claims against SkyWave for loss, damage, liability, or expense
(including lawyers’ fees) arising out of or related to the sale by a Solution Provider or any
Solution Provider Reseller, or the use by any end user, of any product or network service.
6. Application Controller API Reference
T11, Version 1.01vi
Limited Liability
SkyWave’s liability is limited to the cost of repair or replacement of any of SkyWave’s
products during the warranty period. Consequential, indirect, or similar damages
associated with product application and usages are disavowed. SkyWave’s products are
not suitable for life critical applications. SkyWave’s aggregate liability shall in no
circumstances exceed the product’s price as paid to SkyWave and this limitation of
liability is reasonable given the price of SkyWave’s products, which reflect reasonable
allocation.
Warranty
SkyWave warrants its products and services will perform in accordance with SkyWave’s
specifications and will be free from defects in material and workmanship for a period of
fifteen (15) months from date of shipment. This warranty is limited to the repair and/or
replacement of any defective components experienced under normal specified operating
use and storage conditions, at SkyWave’s discretion. It does not cover any damages
caused or associated with the product’s misuse. Notify your Service Provider of any
defective products. Ship any defective product, along with a fault report, back to the
Solution Provider according to the Solution Provider’s instructions. SkyWave is not
responsible for corrosion damage caused by improperly assembled or installed cables.
Warranty is void if the unit is opened.
A fault report is required for each unit returned under warranty. Please contact
SkyWave’s customer support.
7. Application Controller API Reference
T11, Version 1.011
1 Bus Application Controller Overview
SureLinx 8100c offers Solution Providers (SP) a more powerful application design
environment by providing an embedded microcontroller (Bus application controller) to
process complex tasks, not easily managed with SkyWave’s previous script programming
[T8]. The SureLinx 8100c includes all the capabilities of SureLinx 8100. In addition,
more input and output feeds for local sensors, actuators, and peripheral devices are
available using serial and bus interfaces.
Housed within the SureLinx 8100c, the Bus application controller is a daughter card that
communicates with the SureLinx terminal controller (for satellite and GPRS modems,
GPS module, and other physical interfaces). Figure 1 shows how the Bus application
controller connects to the terminal controller. Refer to [T7] for a functional block
diagram of the SureLinx 8100c (terminal controller and Bus application controller).
Figure 1 Terminal Controller and the Bus Application Controller
Bus Application Controller API and Communications Interface
The Bus application controller connects to the terminal controller (terminal) by a
communications interface using a direct serial link. SkyWave provides the Bus
application controller API to facilitate communications between the Bus application
controller and the terminal controller. The Bus application controller typically uses
polling to get information from the terminal controller.
Terminal Controller Messaging API
The terminal controller defines a messaging API, documented in [T9] that provides
generic access to all resources on the board.
The application can still access any resources not explicitly encapsulated by the Bus
application controller API, by implementing the terminal controller messaging API.
Terminal Controller
Bus Application Controller
Ports
Appl Upgrade
UART/SPI
APIMsgs
Programming
User Msgs
I/OLines
18
UART/SPI
APIMsgs
User
Application
CANbus_2RS232
RS485/
RS232/
CANbus_1
Data
Storage
Flash Disk
Data
Storage
Debugger
8. Application Controller API Reference
T11, Version 1.012
Messaging and User Messages
Messaging normally takes place between the Bus application controller and the SP’s
server, using either IsatM2M or GTM/GPRS as a transport mechanism. User messages
are messages sent to- and from- the application. User messages are stored on the terminal
controller’s message database and can be retrieved by the Bus application controller
and/or by an external device connected on the RS232 console. For more detail on the
handling of messages by the terminal controller, refer to [T8] and [T9].
User messages can also be sent between the terminal and an external controller attached
to the RS232 console. In this way, it is possible for an external controller to access the
message database over a console port. Since both an external controller and the Bus
application controller can access the message database, it is the responsibility of the
application designer to ensure they both work together correctly.
Note: SkyWave recommends you configure terminals to transmit data over the GPRS
network at a rate of no more than once every 5 minutes.
Ports
The terminal controller provides access to its resources using a concept of modules and
ports. This includes, but is not limited to, status information of the satellite and GPRS
modems, input/output values and GPS data. For full details on the module and port
infrastructure on the terminal controller, refer to [T9].
The Bus application controller runs a background process to mirror frequently used port
information from the terminal controller for faster access by the application. Appendix A
cross-references these mirrored ports to the API’s. Ports not mirrored are accessible
using the terminal messaging API defined in [T9].
Peripheral Device Interfaces
The terminal controller terminates the RS232 console and up to 18 discrete input/output
(I/O) lines. [T7] describes the characteristics of these lines and their configuration details
are in [T9]. Four of the input/output feeds (standard) share common characteristics, and
the other SureLinx 14 (extended) I/O lines share common characteristics.
Note: You can also use the RS232 console with an external controller to create more
virtual or external I/O’s.
The Bus application controller terminates CANbus_1 or RS485, RS232_1 and
CANbus_2 peripheral ports. Any of these can connect a number of peripherals to the
SureLinx platform. Typical examples of peripherals include sensor/actuator bus network,
keypad/display units and machine interfaces.
Note: At this time, SkyWave does not provide a driver for the CANbus ports, only
hardware devices are equipped.
CANbus_1 and RS485 are mutually exclusive. Only one can be used since they share
common hardware. The application designer is responsible to configure the interfaces so
that only one is used.
9. Application Controller API Reference
T11, Version 1.013
Monitoring and Administration of the Bus Application Controller
Users can monitor and administer the Bus application controller using the following
ports:
Reset To perform a hard or soft reset of the Bus application
controller.
Writing a special key value [see T9] to this port immediately
resets the Bus application controller via a hardware
mechanism.
2 – soft reset in progress
1 – soft reset requested
0 – No status
Application
Program
Upgrade
Writing a special key value [see T9] to this port triggers the
terminal controller to initiate the hardware sequence to
update the Bus application controller with the latest
application program file. This operation is destructive and
non-reversible.
2 – Upgrade forced
1 – Upgrade requested
0 – No status
New Data File
Available
The application polls this port and can communicate that a
new program or data file is available.
Current Program
Version
The application writes the current version number of its
program into this port.
Framework
Version
The version of the application framework currently used on
the Bus application controller.
Application
Timer
Indicates the number of seconds since receiving a message
from the Bus application controller.
Application
Status
Indicates whether or not the application is communicating
properly.
11. Application Controller API Reference
T11, Version 1.015
2 Software Architecture
2.1 Real-Time Operating System (RTOS)
The application protocol interface (API) framework uses OpenRTOS.
OpenRTOS provides:
• task, binary semaphore, and queue services;
• modification of the software design to allow it to work with terminal
applications;
• the user with the ability to create tasks and queues.
2.2 API
Figure 2 describes the terminal’s Bus application controller API.
Figure 2 Application Controller Framework Design
User Application
Application Controller Framework Design API
Application Controller Framework Design
RTOS
Terminal Controller Communication Module
Terminal Controller
RS485
RS232
ECAN
Onboard
EEPROM
DataFlash
Terminal Controller Mirror Module
* RS232 console module
12. Application Controller API Reference
T11, Version 1.016
Modules Description
Terminal
Controller
Communications
Provides the communication support to the terminal controller.
Terminal
Controller
Mirror
Polls certain terminal controller ports such as I/O ports in a
regular interval.
Timer Supports the timer APIs.
IO Supports I/O configure and access to the I/O lines through the
local mirror module.
GPS Provides GPS status access API and GPS power control API.
Terminal
Controller Status
& Control
Provides status access APIs and power control APIs for
IsatM2M and GTM.
File Access Supports the file access APIs.
Port Access Supports the generic terminal controller port access APIs.
Messaging Supports the user messaging APIs.
Console Supports debug print.
Onboard
Memory
Supports the onboard EEPROM and data flash access APIs.
Serial
Communication
Supports the serial access APIs and CAN access APIs.
13. Application Controller API Reference
T11, Version 1.017
3 Development Environment
3.1 Required Development Tools
The following tools must be used:
• Microchip MPLAB IDE version 7.60 or later.
Download the latest MPLAB IDE and the installation instructions from
www.microchip.com
• Microchip MPLAB C Compiler for PIC24 MCUs and dsPIC DSCs (C30
Compiler) version 3.00 or later.
If using an old version of C30, upgrade to version 3.00 or later by downloading
the upgrade patch from www.microchip.com.
One of the following tools should be used:
• Microchip REAL ICE in-circuit emulator.
3.2 Required Skills/Knowledge
Users programming the Bus application controller must have a solid knowledge of C
programming language.
3.3 Application Controller Framework File Structure
The application controller framework file structure (Table 1), is available on SkyWave’s
developer’s toolkit at SkyWave Developers Toolkit>Application Controller1
Table 1 Application Controller Framework File Structure
FOLDER FILE NOTE
appl Contains various sample demo files
slx_comm.h APIs to communicate with terminal controller
slx_console.h APIs to communicate with terminal RS232
console
slx_ctrl.h APIs to control IsatM2M and GPRS
slx_def.h Terminal controller port API module and ports
definitions
slx_ecan.h APIs to access the ECAN communication port.
slx_eeprom.h APIs to access onboard eeprom
framework/include
slx_file.h APIs to access the data files in the terminal
controller flash
1
Refer to the Application Controller folder on the SDK for the most current file names as these may
change.
14. Application Controller API Reference
T11, Version 1.018
slx_flash.h APIs to access onboard flash
slx_gps.h APIs to control and acquire GPS
slx_init.h Platform initialization macros.
slx_io_std.h APIs to control the standard I/Os
slx_io_ext.h APIs to control the SureLinx extended I/Os
slx.led.h APIs to manipulate the onboard LED (may not
always be present)
slx_mirror.h APIs to read the terminal controller’s mirror
ports
slx_port_access.h APIs to read/write the terminal controller’s ports
slx_serial.h APIs to access the serial communication ports
slx_spi.h Used by the framework, not for customer
applications
slx_timer.h APIs to access the local timers
slx_types.h Basic type definitions
slx_usrmsg.h APIs to send/receive terminal controller user
message
slx_wrapper.h Wrappers to access the OpenRTOS functions
Lib
framework.a The library built from the framework and
OpenRTOS
15. Application Controller API Reference
T11, Version 1.019
4 Application Interface Prototypes
File slx_types.h defines the basic interface prototypes such as BOOL, BYTE, WORD16,
WORD32, INT16, and INT32.
4.1 Serial Communication Access
Depending on the actual configuration of the current Bus application controller,
CANbus_1 is shared with RS485 (uses same physical wires). The user application has to
decide which one to support since it cannot support both.
All functions described in this section accept a serial port number – a value of type
SERIAL_PORT declared in the file slx_serial.h.
4.1.1 Serial Configure
Syntax: BOOL SLX_Serial_Configure (SERIAL_PORT port,
SERIAL_CONFIGURE * configure, SERIAL_CALLBACK cb)
Description: This function configures the serial port.
Parameters: < port > - the serial port
< configure > - the configure parameter
< cb > - the character handler
Return: TRUE if success;
FALSE if < configure > is not valid, e.g. the baud rate is not supported;
or if <cb> is NULL
4.1.2 Serial Transmit Tx Busy
Syntax: BOOL SLX_Serial_Tx_Busy (SERIAL_PORT port)
Description: This function returns the status of the serial transmitter.
Parameters: < port > - the serial port
Return: TRUE if the serial transmitter is busy in transmitting data;
FALSE if the serial transmitter is idle.
4.1.3 Serial Write
Syntax: BOOL SLX_Serial_Write (SERIAL_PORT port, BYTE * buffer,
BYTE length )
Description: This function writes to the serial driver’s transmit buffer.
It either writes all the data in buffer or write nothing in case of failure.
Parameters: < port > - the serial port to write
< buffer > - the pointer to the buffer to be transmitted
< length > - length of the bytes to transmit
16. Application Controller API Reference
T11, Version 1.0110
Return: TRUE if it has written all the data in buffer;
FALSE otherwise.
4.2 Terminal Controller Communication
File slx_comm.h defines the terminal controller access related APIs and types.
Syntax: BOOL SLX_Send (SLX_MESSAGE * txMsg,
SLX_MESSAGE * rxMsg, WORD16 timeout_ms)
Description: This function sends a terminal format to the terminal controller. If rxMsg
is non-NULL, it also waits for a response from the terminal controller, up
to the timeout value.
Parameters: < txMsg > - the message to transmit
< rxMsg > - space to store the received message; can be
NULL if reply not expected
< timeout_ms > - the timeout in mill seconds for waiting the
reply
Return: TRUE if success;
FALSE if sending the message failed, waiting for the reply timed out or
insufficient resources.
Note: The Bus application controller works in a request/response mode with the
exception of the unsolicited RS232 console message. The response should
match the prefix, class, and type of the request. If there is no match or it is not
an RS232 console message, it is discarded.
4.3 Terminal Controller Mirrored Ports Access
File slx_mirror.h defines the mirrored port access related APIs and types.
4.3.1 Read Mirrored Port
Syntax: WORD32 SLX_Mirror_Read (MIRROR_INDEX index)
Description: This function reads the value of a mirrored port.
Parameters: < index > - the index for the mirrored port to read
Return: The mirrored port value.
Note: The Bus application controller keeps querying a group of terminal
controller ports on a regular interval. The obtained port values are stored
in a mirror table with mirrored port indexes. Appendix A shows the
mirrored modules and ports.
17. Application Controller API Reference
T11, Version 1.0111
4.3.2 Registered Mirrored Port Change Callback
Syntax: VOID SLX_Mirror_Register (MIRROR_INDEX index,
MIRROR_CLLBACK cb)
Description: This function registers the callback function for the change of the value
of a mirrored port.
Parameters: < index > - the index for the mirrored port
< cb > - the callback function to register
Note: The Bus application controller queries a group of terminal controller ports in a
regular interval. If the value changes, this callback is invoked.
4.4 I/O Access
Files slx_io_std.h and slx_io_ext.h define the terminal I/O access related APIs and types.
4.4.1 Standard I/O Line Setup
Syntax: BOOL SLX_IO_STD_Setup (SLX_IO_STD_ID id,
SLX_IO_STD_TYPE type)
Description: This function sets-up a standard I/O line.
Parameters: < id> - ID of a standard I/O line
< type> - the type of I/O line
Return: TRUE if success;
FALSE if < id> is out of the range of SLX_IO_STD _ID
or < type> is out of the range of SLX_IO_STD_TYPE .
4.4.2 Standard I/O Line Read
Syntax: BOOL SLX_IO_STD_Read (SLX_IO_STD_ID id,
WORD16 * value);
Description: This function reads the raw value of a standard I/O line.
Parameter: < id> - ID of a standard I/O line
<value> - value of the I/O line
Return: TRUE if success,
FALSE if < id> is out of the range of SLX_IO_STD_ID
or the I/O has not been configured yet.
18. Application Controller API Reference
T11, Version 1.0112
4.4.3 Standard I/O Line Write
Syntax: BOOL SLX_IO_STD_Write (SLX_IO_STD_ID id, WORD16 value);
Description: This function writes to an standard I/O output.
Parameters: < id > - ID of a standard I/O line
< value > - value of the I/O line
Return: TRUE if success,
FALSE if < id> is out of the range of SLX_IO_STD_ID
or it has not been configured as an output line.
4.4.4 Extended I/O Line Setup
Syntax: BOOL SLX_IO_EXTENDED_Setup (SLX_IO_EXTENDED _ID
id, SLX_ IO_EXTENDED_TYPE type);
Description: This function sets-up an extended I/O line.
Parameters: < id> - ID of an extended I/O line
< type> - the type of I/O line
Return: TRUE if success;
FALSE if < id> is out of the range of SLX_ IO_EXTENDED _ID
or < type> is out of the range of SLX_ IO_EXTENDED_TYPE .
4.4.5 Extended I/O Line Read
Syntax: BOOL SLX_ IO_EXTENDED_Read (SLX_ IO_EXTENDED _ID id,
WORD16 * value);
Description: This function reads the raw value of an extended IO line.
Parameter: < id> - ID of an extended I/O line
<value> - value of the I/O line
Return: TRUE if success,
FALSE if < id> is out of the range of SLX_IO_EXTENDED_ID
or the I/O has not yet been configured.
19. Application Controller API Reference
T11, Version 1.0113
4.4.6 Extended I/O Line Write
Syntax: BOOL SLX_ IO_EXTENDED_Write (SLX_ IO_EXTENDED_ID id,
WORD16 value);
Description: This function writes to an extended output.
Parameters: < id > - ID of an extended I/O line
< value > - value of the I/O line
Return: TRUE if success,
FALSE if < id> is out of the range of SLX_ IO_EXTENDED_ID
or it has not been configured as an output line.
4.5 Timer
The timer APIs operate the local timers. These timers are not related to the configuration
parameter timers of the terminal.
File slx_timer.h defines the timer related APIs and types.
4.5.1 Timer Start
Syntax: BOOL SLX_Timer_Start (SLX_TIMER_ID id, TIME_IN_MS
timeout, TIMER_HANDLER * handler );
Description: This function starts a timer and registers its callback function.
Parameters: < id > - ID of the timer to be started
< timeout > - timeout value which is rounded to 100 milli-
second granular by truncating
<handler> - pointer to the call back function invoked when
timer expires. It can be NULL
Return: TRUE if success;
FALSE if <id> is out of the range of SLX_TIMER_ID
or timer service is not accessible.
CAUTION: The Timer handler is not allowed to call the Timer APIs.
4.5.2 Timer Stop
Syntax: BOOL SLX_Timer_Stop (SLX_TIMER_ID id);
Description: This function stops the timer <id>.
Parameters: < id > - ID of the timer to be stopped
Return: TRUE if success;
FALSE if <id> is out of the range of SLX_TIMER_ID
or Timer service is not accessible.
20. Application Controller API Reference
T11, Version 1.0114
4.5.3 Timer Read
Syntax: BOOL SLX_Timer_Read (SLX_TIMER_ID id,
TIME_IN_MS * remaining, BOOL * enabled);
Description: This function returns the remaining of the timer <id>.
Parameters: < id > - ID of the timer to read
< remaining > - remaining time before expires
< enabled > - whether the timer has started
Return: TRUE if success;
FALSE if <id> is out of the range of SLX_TIMER_ID or timer service is
not accessible.
4.5.4 Timer Clock
Syntax: BOOL SLX_Timer_Clock (BYTE * hour, BYTE * minute,
BYTE * second);
Description: This function gets UTC time of day.
Parameters: < hour > - hours (0 ~ 23)
< minute > - minutes (0 ~ 59)
< second > - seconds (0 ~ 59)
Return: TRUE if success;
FALSE if the time and date are not available.
4.6 GPS
File slx_gps.h defines the GPS related APIs and types.
Note: GPS functionality is only available on SureLinx terminals.
4.6.1 GPS Status
Syntax: BOOL SLX_GPS_Status ( SLX_GPS_STATUS * status )
Description: This function returns the basic GPS information from the mirror ports.
Parameters: < status > - GPS status structure
Return: TRUE if success;
FALSE if GPS information is not available.
21. Application Controller API Reference
T11, Version 1.0115
4.6.2 GPS Power
Syntax: BOOL SLX_GPS_Power (BOOL onOff)
Description: This function turns on or off the power of the GPS.
Parameters: < onOff > - power on if onOff is set to TRUE, power off
otherwise
Return: TRUE if success;
FALSE if not.
4.6.3 GPS Distance
Syntax: INT32 SLX_GPS_Distance (INT32 sourceLatitude, INT32
sourceLongitude, INT32 destLatitude, INT32 destLongitude)
Description: This function calculates the distance between two points (source and
destination).
Parameters: < sourceLatitude > - source latitude
< sourceLongitude > - source longitude
< destLatitude > - destination latitude
< destLongitude > - destination longitude
Return: Distance in meters.
4.7 Terminal Controller Status & Control
File slx_ctrl.h defines the Terminal Controller Status and Control module related APIs
and types.
4.7.1 Terminal Controller Power Control
Syntax: BOOL SLX_Power_Control (SLX_DEVICE device, BOOL onOff )
Description: This function turns on or off the power of the terminal controller
<device>.
Parameters: < device > - a device on the terminal controller
< onOff > - power on if onOff is set to TRUE, power off
otherwise
Return: TRUE if success;
FALSE if <device> is not a valid device defined in SLX_DEVICE.
22. Application Controller API Reference
T11, Version 1.0116
4.7.2 Terminal Controller Power Status
Syntax: BOOL SLX_Power_Available (SLX_DEVICE device)
Description: This function returns the power status of the terminal <device>.
Parameters: < device > - a device on the terminal controller
Return: TRUE if power on;
FALSE if power off.
4.8 Console
Console APIs are for debugging purposes or for communication between the Bus
application controller and an external controller.
File slx_console.h defines the RS232 console related APIs and types.
4.8.1 Console Output
Syntax: BOOL SLX_Console_Output (BYTE * buffer, BYTE length )
Description: This function writes to the RS232 console.
This function either writes all data in the buffer or writes nothing in case
of failure.
Parameters: < buffer > - buffer to write from
< length > - length of the bytes to write
Return: TRUE if it has written all the data in buffer;
FALSE otherwise.
4.8.2 Console Register Callback
Syntax: void SLX_ConsoleRegisterCallback (CONSOLE_CALLBACK
callback)
Description: This function registers the console message callback function. The
callback function is invoked when console message is received.
Parameters: < callback > - RS232 console callback
23. Application Controller API Reference
T11, Version 1.0117
4.9 Terminal Controller Messaging
File slx_usrmsg.h defines the terminal controller user messaging related APIs and types.
4.9.1 Add User Message
Syntax: BOOL SLX_AddTxMessage (SLX_TX_MSG * txMsg
WORD16 * serialNumber )
Description: This function adds a user message to the transmit message queue on the
terminal controller.
This function either writes all data or writes no data.
Parameters: < txMsg > - the user message
< serialNumber > - the serial number assigned to the message once
added
Return: TRUE if the user message is successfully written into the transmit queue;
FALSE if data buffer is too large to be handled or the user transmit
queue is full.
Note: The Message Database Access section of [T9] describes the fields of
SLX_TX_MSG.
4.9.2 Get User Message
Syntax: BOOL SLX_GetRxMessage (WORD16 *serialNumber,
SLX_MSG_STATE *state, SLX_RX_MSG * rxMsg );
Description: This function retrieves a user message from the message database on the
terminal controller.
Parameters: < serialNumber > - the serial number of the message to retrieve,
0x0000 for the previous message, or 0xFFFF for
the next message
< state > - the state of the retrieved message
<rxMsg > - the retrieved user message
Return: TRUE if a user message has been retrieved from user receive queue;
FALSE if the serial number is invalid or the message is too large.
Note: The Message Database Access section of [T9] describes the fields of
SLX_RX_MSG.
24. Application Controller API Reference
T11, Version 1.0118
4.9.3 Remove User Message
Syntax: BOOL SLX_RemoveRxMessage (WORD16 * serialNumber );
Description: This function removes a user message from the message database on the
terminal controller.
Parameters: < serialNumber > - the serial number of the message to remove
Return: TRUE if a user message has been removed from user receive queue;
FALSE if the serial number is invalid.
4.9.4 Set Rx Message Filter
Syntax: BOOL SLX_SetRxFilter (SLX_RX_MSG_FILTER * filter);
Description: This function sets a filter for retrieving user messages from the message
database on the terminal controller.
Parameters: < filter > - The filter to set. This is also filled in with the
current filter value upon exit.
Return: TRUE if the filter was set correctly;
FALSE otherwise.
Note: The Message Database Access section of [T9] describes the fields of
SLX_RX_MSG_FILTER.
4.9.5 Get Rx Message Filter
Syntax: BOOL SLX_GetRxFilter (SLX_RX_MSG_FILTER * filter);
Description: This function retrieves the current Rx message filter value from the
terminal.
Parameters: < filter > - the current filter
Return: TRUE the filter was retrieved successfully;
FALSE otherwise.
Note: The Message Database Access section of [T9] describes the fields of
SLX_RX_MSG_FILTER.
25. Application Controller API Reference
T11, Version 1.0119
4.10File Access
All the file access API functions are blocked.
4.10.1 File Open
Syntax: BOOL SLX_File_Open (BYTE index, BYTE * id);
Description: This function opens a data file in the file group 1 (application) with file
type 2 (data) in flash memory.
Parameters: < index > - the index of the data file (1 ~ 12)
< id > - handle of the file opened
Return: TRUE if the file already exists and has not been opened yet;
FALSE otherwise.
4.10.2 File Close
Syntax: BOOL SLX_File_Close (BYTE id);
Description: This function closes a file in flash memory.
Parameters: < id > - handle of the file to close
Return: TRUE if the file has been opened;
FALSE if the file doesn’t exist or has not been opened.
4.10.3 File Seek
Syntax: BOOL SLX_File_Seek (BYTE id, WORD32 offset);
Description: This function moves access pointer to the <offset> of file <id>
Parameters: < id > - the handle of the file to seek
< offset > - the offset to seek
Return: TRUE if the file has been opened and the offset is valid;
FALSE otherwise.
26. Application Controller API Reference
T11, Version 1.0120
4.10.4 File Read
Syntax: BOOL SLX_File_Read (BYTE id, BYTE * buffer,
WORD16 lengthToRead, WORD16 * length);
Description: This function reads from file <id> into buffer <buffer>
Parameters: < id > - the handle of the file to read
< buffer > - to store the data file
< lengthRead > - the number of bytes which are wanted to read
< length > - length of the bytes actually read
Return: TRUE if the file has been read successfully;
FALSE otherwise.
4.11EEPROM Access
A 32Kbit EEPROM is populated in the Bus application controller. The address should be
from 0x0000 to 0x0FFF.
4.11.1 EEPROM Read
Syntax: BOOL SLX_EEPROM_Read (WORD16 address, BYTE * buffer,
WORD16 length);
Description: This function reads <length> bytes from the memory in EEPROM
with starting address <address> into buffer <buffer>
Parameters: < address > - the start address to read
< buffer > - to store the data
< length > - the number of bytes which are wanted to read
Return: TRUE if the data has been read successfully;
FALSE otherwise.
4.11.2 EEPROM Write
Syntax: BOOL SLX_EEPROM_Write (WORD16 address, BYTE * buffer,
WORD16 length);
Description: This function writes <length> bytes from buffer <buffer> to the memory
in EEPROM with starting address <address>. This is a blocking
function.
Parameters: < address > - the start address to write
< buffer > - the data to write
< length > - the number of bytes to write
Return: TRUE if the data has been written successfully;
FALSE otherwise.
27. Application Controller API Reference
T11, Version 1.0121
4.12Flash Access
A 16Mbit flash is populated in the Bus application controller. The flash is accessed by
pages. The number of the pages should be from 0 to 4095 and each page has 528 bytes.
4.12.1 Flash Page Read
Syntax: BOOL SLX_Flash_Page_Read (WORD16 page, BYTE * buffer);
Description: This function reads 528 bytes from the page in flash with page number
<page> into buffer <buffer>
Parameters: < page > - the page number
< buffer > - to store the data
Return: TRUE if the data has been read successfully;
FALSE otherwise.
4.12.2 Flash Page Write
Syntax: BOOL SLX_Flash_Page_Write (WORD16 page, BYTE * buffer);
Description: This function write 528 bytes to the page in flash with page number
<page> from buffer <buffer>
Parameters: < page > - the page number
< buffer > - data to write
Return: TRUE if the data has been written successfully;
FALSE otherwise.
4.13ECAN Access
Depending on the actual configuration of the current Bus application controller,
CANbus_1 is shared with RS485 (uses same physical wires). The user application has to
decide which one to support since it cannot support both.
File slx_ecan.h defines the ECAN access related APIs and types.
28. Application Controller API Reference
T11, Version 1.0122
4.13.1 ECAN Configure
Syntax: BOOL SLX_ECAN_Configure (ECAN_PORT port,
WORD32 identifier, BOOL ide, ECAN_BAUDRATE baudrate,
ECAN_CALLBACK cb);
Description: This function configures the serial port.
Parameters: < port > - the ECAN port
< identifier > - the receive filter identifier
< ide > - whether identifier is extended or standard
< baudrate > - the baud rate
< cb > - the receive buffer handler
Return: TRUE if successful;
FALSE if port is not valid or the baud rate is not supported.
4.13.2 ECAN Transmit Tx Busy
Syntax: BOOL SLX_ECAN_Tx_Busy (ECAN_PORT port);
Description: This function returns the status of the ECAN transmitter.
Parameters: < port > - the ECAN port
Return: TRUE if the ECAN transmitter is busy transmitting data;
FALSE if the ECAN transmitter is idle.
4.13.3 ECAN Transmit
Syntax: BOOL SLX_Serial_Write (SERIAL_PORT port, BYTE * buffer,
BYTE length); BOOL SLX_ECAN_Tx (ECAN_PORT port,
WORD32 identifier, BOOL ide, BOOL remoteTransmit, BYTE * buffer,
BYTE length);
Description: This function transmits a buffer. It either writes all the data in the buffer
or writes nothing in case of failure.
Parameters: < port > - the ECAN port to write
< identifier > - the identifier to be transmitted
< ide > - whether identifier is extended or standard
< remoteTransmit > - if remote transmit request
< buffer > - the pointer to the buffer to be transmitted
<length> - length of the bytes to transmit
Return: TRUE if has written all the data in the buffer;
FALSE otherwise.
29. Application Controller API Reference
T11, Version 1.0123
4.14Port Access
All the port access API functions are blocked.
4.14.1 Port Read
Syntax: BOOL SLX_Port_Read (BYTE module, BYTE port, WORD32 * value);
Description: This function reads from <port> of <module>
Parameters: < module > - module ID
< port > - port number
< value > - value of the port stored as WORD32
Return: TRUE if success;
FALSE if <module> or <port> doesn’t exist, or nothing is returned from
the terminal controller.
4.14.2 Port Write
Syntax: BOOL SLX_Port_Write (BYTE module, BYTE port, WORD32 value);
Description: This function writes to <port> of <module>. This is a blocking function.
An internal 2 second timeout for write operation is set.
Parameters: < module > - module ID
< port > - port number
< value > - value of the port stored as WORD32
Return: TRUE if write is successful;
FALSE if module or port doesn’t exist, write operation has failed or port
is write only.
4.15RTOS Wrapper
Provided are OpenRTOS function wrappers.
File slx_wrapper.h defines the RTOS wrapper APIs and types.
4.15.1 RTOS Start Wrapper
Syntax: void SLX_RTOS_StartScheduler(void);
Description: This function calls the RTOS scheduler start function.
4.15.2 RTOS Task Yield Wrapper
Syntax: void SLX_RTOS_TaskYield (void);
Description: This function calls the RTOS task yield function.
30. Application Controller API Reference
T11, Version 1.0124
4.15.3 RTOS Task Create Wrapper
Syntax: void SLX_RTOS_TaskCreate (TASK_FUNCTION func,
WORD16 stackSize, BYTE priority);
Description: This function calls the RTOS task create function.
Parameters: < func > - task function
< stackSize > - the stack size of the task
< priority > - the priority of the task (1 ~ 7)
Note: The minimum stack size is 105 bytes. The user must increase this to cover all
the variables encountered through the deepest series of functions it may call
during the life of the task, including any padding for alignment of data.
32. Application Controller API Reference
T11, Version 1.0126
Document Versions
Version Date Details
01 June 2008 Initial release of document
1.01 Aug 2008 Minor fix to an image, added an additional false
condition for port write.
33. Application Controller API Reference
T11, Version 1.0127
Index
basic interface prototypes............................9
Bus application controller............................v
framework design ....................................5
modules ...................................................6
ports.........................................................3
description
Bus application controller........................1
communications interface........................1
interfaces peripheral device.....................2
ports.........................................................2
terminal controller messaging .................1
user messages ..........................................2
EEPROM
address...................................................20
framework file structure location ................7
framework files............................................7
functional block diagram.................See [T7]
interfaces
CANbus...................................................2
RS232 ......................................................2
RS485 ......................................................2
module ID..................................................25
modules
console.................................................... 6
file access................................................ 6
GPS......................................................... 6
I/O lines .................................................. 6
messaging ............................................... 6
onboard memory..................................... 6
port access............................................... 6
serial communication.............................. 6
terminal controller communications....... 6
terminal controller mirror ....................... 6
terminal controller status and control ..... 6
timer........................................................ 6
port numbering ......................................... 25
reference ..................................................... v
RTOS.......................................................... 5
SkyWave Developer’s Toolkit (SDK)........ ii
stack size................................................... 24
terminal controller ...................................... v
user serviceable parts................................. vi
warranty..................................................... vi
