Atop SE59XX-SDK User manual

SE59XX-SDK
Software development Kit
User Manual
V1.2
SE59XX-SDK Family
Software Development Kit
User Manual
V1.2
May 3rd, 2018
Atop Technologies, Inc .

SE59XX-SDK
Software development Kit
User Manual
V1.2
This PDF Document contains internal hyperlinks for ease of navigation.
For example, click on any item listed in the Table of Contents to go to that page.
General Description
User Guide
Published by:
Atop Technologies, Inc.
2F, No. 146, Sec. 1, Tung-Hsing Rd,
30261 Chupei City,
Hsinchu County
Taiwan, R.O.C.
Tel: [phone]
Fax: [phone]
[e-mail]
www.atoponline.com
www.atop.com.tw

SE59XX-SDK
Software development Kit
User Manual
V1.2
Important Announcement
The information contained in this document is the property of Atop Technologies, Inc., and is supplied for the sole
purpose of operation and maintenance of Atop Technologies, Inc., products.
No part of this publication is to be used for any other purposes, and it is not to be reproduced, copied, disclosed,
transmitted, stored in a retrieval system, or translated into any human or computer language, in any form, by any
means, in whole or in part, without the prior explicit written consent of Atop Technologies, Inc.,
Offenders will be held liable for damages and prosecution.
All rights, including rights created by patent grant or registration of a utility model or design, are reserved.
Disclaimer
We have checked the contents of this manual for agreement with the hardware and the software described. Since
deviations cannot be precluded entirely, we cannot guarantee full agreement. However, the data in this manual is
reviewed regularly and any necessary corrections will be included in subsequent editions.
Suggestions for improvement are welcome.
All other product’s names referenced herein are registered trademarks of their respective companies.
Documentation Control
Author:
Carlos Hsu, Willy Lin, Matteo Tabarelli
Revision:
1.1
Revision History:
Released
Creation Date:
5 February 2018
Last Revision Date:
4 May 2018
Product Reference:
SE5901 (SDK), SE5901B (SDK), SE5904D (SDK), SE5908 (SDK),
SE5916 (SDK), SE5900A (SDK), SE5908A (SDK), SE5901A (SDK)
Document Status:
Released

SE59XX-SDK
Software development Kit
User Manual
V1.2
Table of Contents
1Preface .................................................................................................................................9
1.1 Purpose of the Manual............................................................................................................................9
1.2 Who Should Use This User Manual ........................................................................................................9
1.3 Supported Platform.................................................................................................................................9
1.4 Warranty Period.......................................................................................................................................9
2Introduction to Atop SDK ................................................................................................. 10
2.1 Overview of SE59XX-SDK development environment..........................................................................10
2.2 Description of SDK Folders ...................................................................................................................12
2.3 Firmware upgrade.................................................................................................................................15
2.3.1 Use boot-loader update via console port ..............................................................................................15
2.3.2 Use Device Manager or Device Management Utility.............................................................................19
2.4 Verify current firmware version.............................................................................................................20
2.5 Installing a Cross-Compiler...................................................................................................................21
2.6 Compiling Procedure for Atop Applications..........................................................................................21
2.7 Compiling new Applications..................................................................................................................21
2.8 Download new Applications to the device ............................................................................................22
2.8.1 Using TFTP protocol .............................................................................................................................22
2.8.2 Using FTP protocol................................................................................................................................22
2.9 Login or Remote Login to the device ....................................................................................................23
2.9.1 Remote Login ........................................................................................................................................23
2.9.2 Use a debug command line to Login ....................................................................................................23
2.10 Automatic execution on Startup of Custom-Applications....................................................................23
2.11 Startup messages.................................................................................................................................24
3Hardware Specifications.................................................................................................. 29
3.1 Packing List ...........................................................................................................................................29
3.2 Optional Accessories.............................................................................................................................29
3.3 Hardware...............................................................................................................................................31
3.4 External Device’s Overview....................................................................................................................34
3.5 Serial Pin Assignments..........................................................................................................................38
3.5.1 SE5901 Pin Assignments for Serial Interfaces .....................................................................................38
3.5.2 SE5904D Pin Assignments ...................................................................................................................39
3.5.3 SE5901B Pin Assignments....................................................................................................................41
3.5.4 SE5908A/ SE5916A Pin Assignments ..................................................................................................42
4Software Specifications................................................................................................... 44
4.1 COM Port Interface................................................................................................................................44
4.1.1 Program COM port interface.................................................................................................................44
4.2 Network Interface..................................................................................................................................45
4.3 Other Interfaces.....................................................................................................................................45
4.3.1 Buzzer....................................................................................................................................................46
4.3.2 Digital Inputs..........................................................................................................................................46
4.3.3 Digital Outputs.......................................................................................................................................46
4.3.4 Relay Outputs........................................................................................................................................46
4.3.5 LCM (SE5908 / SE5916 only)................................................................................................................46
4.3.6 Reset Button..........................................................................................................................................47

SE59XX-SDK
Software development Kit
User Manual
V1.2
4.3.7 Hardware Watchdog Timer...................................................................................................................47
4.3.8 LEDs ......................................................................................................................................................47
4.3.9 3G/4G Cellular (SE5901B only) .............................................................................................................48
4.3.10 RTC Interface ........................................................................................................................................48
5Testing interfaces............................................................................................................. 49
5.1 Test COM port interface –transmit and receive ..................................................................................49
5.1.1 Test COM port interface by using atop_tcp_server...............................................................................49
5.1.1.1Test Method ..........................................................................................................................................49
5.1.1.2Test Execution.......................................................................................................................................49
5.2 Test Buzzer interface ............................................................................................................................51
5.3 Test Digital Input ...................................................................................................................................53
5.4 Test Digital Output.................................................................................................................................53
5.5 Test Hardware Relay Output.................................................................................................................53
5.6 Test Hardware Button...........................................................................................................................53
5.7 Test Hardware Watchdog Interface (WDT) ..........................................................................................53
5.8 Test device LED.....................................................................................................................................54
5.9 Test RTC interface ................................................................................................................................54
5.9.1 Setup RTC time: ....................................................................................................................................54
5.9.2 Read RTC time:......................................................................................................................................55
5.9.3 RTC2system..........................................................................................................................................55
5.9.4 system2RTC..........................................................................................................................................55
5.10 Using NOR Flash –JFFS2 ....................................................................................................................55
5.11 MQTT.....................................................................................................................................................55
5.12 Firmware upgrade.................................................................................................................................56
6Software API Reference................................................................................................... 57
6.1 File List...................................................................................................................................................57
7Data Structure Documentation........................................................................................ 58
7.1 sessiontag Struct Reference.................................................................................................................58
7.1.1 data fields ..............................................................................................................................................58
7.2 Network APIs.........................................................................................................................................58
7.2.1 Functions...............................................................................................................................................58
7.3 Network APIs Function documentation................................................................................................59
7.3.1 void AtopSDK4GHWReset (void )..........................................................................................................59
7.3.2 void AtopSDKSet4GApn (char * apn)....................................................................................................60
7.3.3 void AtopSDKSet4GConnect (void).......................................................................................................60
7.3.4 void AtopSDKSet4GDialOnBoot (int value)............................................................................................60
7.3.5 void AtopSDKSet4GDisconnect (void) ..................................................................................................61
7.3.6 void AtopSDKSet4GPinDisable (void)....................................................................................................61
7.3.7 void AtopSDKSet4GPinEnable (char * pinCode)...................................................................................61
7.3.8 void AtopSDKSet4GReConnect (int value)............................................................................................61
7.3.9 void AtopSDKSetNetDefGateway (int eth)............................................................................................61
7.3.10 void AtopSDKSetNetGateway (int eth, char *gw) .................................................................................62
7.3.11 void AtopSDKSetNetIP (int eth, char *ip)...............................................................................................62
7.3.12 void AtopSDKSetNetMask (int eth, char *mask)...................................................................................63
7.4 EEPROM User Name and Password Settings APIs..............................................................................63
7.4.1 Functions...............................................................................................................................................63
7.5 EEPROM User Name and Password Settings API Function documentation.......................................64
7.5.1 void AtopSDKSetUserName (char name).............................................................................................64

SE59XX-SDK
Software development Kit
User Manual
V1.2
7.5.2 void AtopSDKSetUserPassword (int password)...................................................................................64
7.6 Run LED API Function documentation .................................................................................................64
7.6.1 Functions...............................................................................................................................................64
7.6.2 void AtopSetRunLed (onMs u32,offMs u32).........................................................................................64
7.7 Alarm LED API Function documentation ..............................................................................................65
7.7.1 Functions...............................................................................................................................................65
7.7.2 void AtopSetAlarmLed (u32 value)........................................................................................................65
7.8 Read Reset Button API..........................................................................................................................65
7.8.1 Functions...............................................................................................................................................65
7.8.2 int AtopButton (void)..............................................................................................................................65
7.9 Use Buzzer API documentation ............................................................................................................66
7.9.1 Functions...............................................................................................................................................66
7.9.2 Macros...................................................................................................................................................66
7.9.3 void AtopBuzzerOnOff (int value) ..........................................................................................................66
7.10 Read Digital Inputs API documentation ................................................................................................66
7.10.1 Functions...............................................................................................................................................66
7.10.2 int AtopGetDI (int index) ........................................................................................................................67
7.11 Write Digital Output API documentation ...............................................................................................67
7.11.1 Functions...............................................................................................................................................67
7.11.2 int AtopSetDO (int index, int value)........................................................................................................67
7.12 Hardware Watchdog API documentation.............................................................................................67
7.12.1 Functions...............................................................................................................................................67
7.12.2 Macros...................................................................................................................................................68
7.12.3 void atop_hwd_clear (void)....................................................................................................................68
7.12.4 void atop_hwd_disable (void) ................................................................................................................68
7.12.5 void atop_hwd_enable (void) .................................................................................................................68
7.13 Wi-Fi USB Dongle control APIs documentation....................................................................................69
7.13.1 Functions...............................................................................................................................................69
7.13.2 void create_default_ini_file (void)...........................................................................................................70
7.13.3 void get_key_mgmt (char key_mgmt)...................................................................................................70
7.13.4 int get_psk(char psk) .............................................................................................................................70
7.13.5 int get_ssid (char ssid)...........................................................................................................................71
7.13.6 int parse_setting (void) ..........................................................................................................................72
7.13.7 void run_connection (void) ....................................................................................................................72
7.13.8 int set_key_mgmt (int mode).................................................................................................................72
7.13.9 int set_psk (char psk_name)..................................................................................................................73
7.13.10 int set_ssid (char ssid_name) .......................................................................................................74

SE59XX-SDK
Software development Kit
User Manual
V1.2
Table of Figures
Figure 2.1 Architecture of SE5904D SDK............................................................................................................10
Figure 2.2 Console firmware update- connections.............................................................................................15
Figure 2.3 COM port Parameters for Console Firmware update.........................................................................16
Figure 2.4 TFPD32 appearance after execution ..................................................................................................16
Figure 2.5 SE5904D Boot loader menu................................................................................................................17
Figure 2.6 LAN Settings........................................................................................................................................18
Figure 2.7 LAN1 settings......................................................................................................................................18
Figure 2.8 TFTP download menu ........................................................................................................................18
Figure 2.9 SE59XX connection scheme (example on SE5904D) ........................................................................19
Figure 2.10 Firmware update prompt..................................................................................................................19
Figure 2.11 Firmware selection............................................................................................................................20
Figure 2.12 Firmware version - Console..............................................................................................................20
Figure 2.13 Firmware version in Device Management Utility (English)............................................................... 21
Figure 2.14 FTP access credentials.....................................................................................................................22
Figure 2.15 FTP Download with FileZilla..............................................................................................................22
Figure 2.16 Command line Login.........................................................................................................................23
Figure 3.1 DB9 Pin Number..................................................................................................................................38
Figure 3.2 TB5 Pin Number..................................................................................................................................38
Figure 3.3 DB9 Pin Number..................................................................................................................................39
Figure 3.4 Terminal Block (TB-5) Pin Number .....................................................................................................39
Figure 3.5 DB9 Pin Number..................................................................................................................................41
Figure 3.6 2 x 7-pin Male Terminal Block.............................................................................................................41
Figure 3.7 DB9 Pin Number..................................................................................................................................42
Figure 3.8 Terminal Block (TB-5) Pin Number .....................................................................................................42
Figure 5.1 COM1 loopback test connection.........................................................................................................49
Figure 5.2 Process execution on SE5904D, example ..........................................................................................50
Figure 5.3 Setup TCPtest.exe for COM port loopback test..................................................................................50
Figure 5.4 Result of loopback test .......................................................................................................................51
List of Tables
Table 2.1 Content of 3rd party folder ....................................................................................................................12
Table 2.2 Content of Software folder...................................................................................................................12
Table 2.3 List of programs in filesystem folder ...................................................................................................14
Table 2.4 Content of build folder..........................................................................................................................14
Table 3.1 Packing List ..........................................................................................................................................29
Table 3.2 Optional Accessories............................................................................................................................29
Table 3.3 Hardware features ...............................................................................................................................31
Table 3.4 SE5901 Pin Assignment for DB9 to RS-232/RS-422/RS-485 Connector........................................... 38

SE59XX-SDK
Software development Kit
User Manual
V1.2
Table 3.5 SE5901 Pin Assignment for TB5 to RS-232/RS-422/RS-485 Connector............................................38
Table 3.6 MB5904D Pin Assignment for DB9 to RS-232/RS422/RS-485 Connectors.......................................39
Table 3.7 MB5904D Pin Assignment for 5-Pin Terminal Block to RS-232/RS-422/RS-485 Connectors ...........39
Table 3.8 SE5901B Pin Assignment for DB9 to RS-232/RS-485 Connector.......................................................41
Table 3.9 SE5901B 2 x 7-pin Male TB for RS-232/485(COM 1),RS-232(COM 2) Relay and DI pin-assignment.41
Table 3.10 SE5908A/16A Pin Assignment for DB9 to RS-232/RS422/RS-485 Connectors ..............................42
Table 3.11 SE5908A/16A Pin Assignment for 5-Pin Terminal Block to RS-232/RS-422/RS-485 Connectors...42
Table 4.1 Sample programs for COM port interface ...........................................................................................44
Table 4.2 SE59XX device node.............................................................................................................................44
Table 4.3 SE59XX Programming commands per device node...........................................................................45
Table 4.4 SE59XX ioctl command of COM Port ..................................................................................................45
Table 4.5 Sample programs for TCP server connection to COM port communication......................................45
Table 4.6 Sample program for Buzzer.................................................................................................................46
Table 4.7 Sample program for Digital Input.........................................................................................................46
Table 4.8 Sample program for Digital Output......................................................................................................46
Table 4.9 Sample program for Relay Output .......................................................................................................46
Table 4.10 Sample program for LCM ..................................................................................................................47
Table 4.11 Sample program for Reset Button.....................................................................................................47
Table 4.12 Sample program for WDT..................................................................................................................47
Table 4.13 Sample program for LEDs..................................................................................................................47
Table 4.14 Sample program for Cellular functions..............................................................................................48
Table 5.1 TCP-port to COM-port mapping...........................................................................................................51

SE59XX-SDK
Software development Kit
User Manual
V1.2
1 Preface
1.1 Purpose of the Manual
This manual supports you in understanding the software SDK architecture of ATOP’s SE59XX Series and
should be a reference guide for application development on this platform.
1.2 Who Should Use This User Manual
This manual is to be used by qualified programmers, network personnel or support technicians who are familiar
with network operations and C Language programming.For any related problems, please contact your local
distributor. If they are unable to assist you, please redirect your inquiries to www.atop.com.tw or
www.atoponline.com.
1.3 Supported Platform
This manual is designed for the SE5901, SE5901B, SE5904D, SE5908, SE5916, SE5900A, SE5908A, and
SE5916A Industrial Serial and Ethernet controller and that model only.
1.4 Warranty Period
ATOP provides a 5-year limited warranty for SE59XX Series.

SE59XX-SDK
Software development Kit
User Manual
V1.2
2 Introduction to Atop SDK
2.1 Overview of SE59XX-SDK development environment
Notice: Please upgrade to the Firmware version on which this SDK document is based.
Figure 2.1 shows the whole architecture of SE59XX SDK. Three types
of Applications are provided in user's layer:
1) ATOP applications: providing multiple sample SDK programs to hardware devices
2) ATOP utility: providing firmware upgrade, network settings and storage mounting tools
3) Third-party : providing 3rd parties software required such as SNMP / Apache / SQLite
In Kernel Layer, Linux 3.14.26 is customized to provide complete networking protocols.
In Driver Layer, device drivers for all Industrial communication interfaces are provided.
In hardware Layer, Customized ARM Cortex-A8 platform and Atop FPGA management core are provided.
Figure 2.1 Architecture of SE5904D SDK

SE59XX-SDK
Software development Kit
User Manual
V1.2

SE59XX-SDK
Software development Kit
User Manual
V1.2
2.2 Description of SDK Folders
Ex t ract sdk_release_YYYYMMDD. ta r .b z2 and refer SDK_Release/ folder ( p lease note that YYYY
corres ponds to the release year, MM to the release month and DD to the release Day).
There are 4 sub-folders :
build : this folder includes build done fi rmware and merge utili ties .
filesys tem: this folder includes root file system and bootup scri p t .
software : this folder includes ATOP library, sample code and header file .
3rd par ty : 3rd par ty utilit ies
The followings are the list of document in "3rdparty" folder:
Table 2.1 Content of 3rd party folder
Folder Name
Description
Busybox-1.23.1
Busybox source
c-ares
C library for asynchronous DNS requests
dhcp-4.1-esv-R13
IPv6 dhcp utilities
email-3.1.3
E-mail utility
gmp-6.1.2
gmp-6utility –for arbitrary precision arithmetic
Hostap
user space daemon for access point and authentication servers.
i2c-tools-3.1.2
I2C tools to manage I2C Bus
iniparser
Ini file parser library
iptables-1.6.1
Tool to manage IP tables
libmodbus-3.1.2
Modbus stack
libnl-3.2.25
libnl suite is a collection of libraries
libpcap-1.7.4
a portable C/C++ library for network traffic capture
libuuid
to generate unique ident for obj to be accessible beyond local system
monit-5.18
Daemon monitor utility
mosquitto-1.4.14
MQTT stack
ncftp-3.2.5
FTP utility
openssl-1.0.2
Openssl library
rtl8192EU_linux_v4.4.1.1
Wi-Fi dongle driver.
strongswan-5.5.2
IPsec VPN
ucarp-1.5.2
allows 2 host share common virtual IP to provide automatic failover
wireless_tools.29
Wifi tools
zlib-1.2.8
Zip library
The followings are the lis t of ap plication p rograms in "software" folder :
Table 2.2 Content of Software folder
Folder Name
Description
include
Reference header file
atop_library
ATOP library
atop_application
Sample code

SE59XX-SDK
Software development Kit
User Manual
V1.2
libatop.so.1.0.0
ATOP library binary

SE59XX-SDK
Software development Kit
User Manual
V1.2
The followings are the lis t of ap plication p rograms in "filesys tem" folder :
Table 2.3 List of programs in filesystem folder
Folder Name
Description
etc
Bootup script, no need to modify under this folder
rootfs.tar.bz2
Pre-build root file system.
The followings are the lis t of ap plication p rograms in "build" folder:
Table 2.4 Content of build folder
Folder Name
Description
Image.dld
Build done FW image.
initrd.uboot
Root file system package
composer
Merge image utility
u-boot.bin
Bootloader image for rescuing device
u-boot.dld
Bootloader image for rescuing device
zlimage
Linux kernel raw image

SE59XX-SDK
Software development Kit
User Manual
V1.2
2.3 Firmware upgrade
There are two ways to upgrade the firmware on the SE59XX platform:
2.3.1 Use boot-loader update via console port
Prepare a Debug Cable (RJ45 to Serial) and a CAT5E Ethernet cable. Then, follow below figure to connect the
Debug port to PC’s COM and CAT5E cable to connect to the Device’s LAN1 Ethernet port to any Host PC’s
Ethernet port.
Figure 2.2 Console firmware update- connections
On your PC, run Windows’ "Super Terminal" setup COM port parameters as follows:
- Port: the connected COM port
- Baud Rate: 115200 bps
- Parity: none
- Data: 8 data bits
- Stop: 1 stop bit
- Flow control: none

SE59XX-SDK
Software development Kit
User Manual
V1.2
Figure 2.3 COM port Parameters for Console Firmware update
With this method, TFTP protocol is used. The TFTP client is already set-up and running inside the SE59XX
platform. Thus, the user needs to execute TFTP server in Windows. An open source version is available for
download and can be found as “tftpd32”. Screenshot below shows "tftpd32.exe" after running the application.
Figure 2.4 TF PD32 ap pearance af te r execution
Now, setup the IP address of the TFTP server. The current folder is the one where "tftpd32.exe" is located.
After executing TFTP server, reboot the target SE59XX platform and press the Escape (“Esc”) key immediately.
A boot-loader menu will be shown as Figure 2.5.

SE59XX-SDK
Software development Kit
User Manual
V1.2
Figure 2.5 SE5904D Boot loader menu

SE59XX-SDK
Software development Kit
User Manual
V1.2
Select item 1 to enter "LAN Setting" menu as Figure 2.6, and setup IP/Netmask/Gateway of LAN1 as Figure 2.7
Figure 2.6 LAN Set tings
Figure 2.7 LAN1 settings
Enter 0 to exit to upper layer menu and select 5 to enter the "TFTP Download" menu, then select 1 to setup
TFTP server IP as Figure 2.8
Figure 2.8 TFTP download menu
After the setup of the server IP is completed, select 2 to download the firmware image.
Note: the extension of the firmware should be .dld

SE59XX-SDK
Software development Kit
User Manual
V1.2
2.3.2 Use Device Manager or Device Management Utility
Please use a CAT5E cable to connect SE59XX to a PC running Windows where ATOP Device Management utility
is already installed. To install Device Management Utility, please download the latest release from ATOP Website
and follow its dedicated user manual for the installation.
The device doesn’t have necessarily to be directly connected to the PC, as long as it is inside the same LAN.
Atop Management Utility will scan the whole network automatically.
Figure 2.9 SE59XX connection scheme (example on SE5904D)
Now, please power on the device and run Atop’s Device Management Utility from your Host PC. Once the device
is running, the utility will list all devices found. If the device doesn’t show up, push the leftmost button (Rescan
function). Once identified, select the device by mouse left button and select "Firmware" >> "Download Firmware"
as per Figure 2.10.
Figure 2.10 Firmware update prompt
Select the firmware (Kernel or AP) from this dialog and select the upgraded file as Figure 2.11. Then, click on the
"Upgrade" button to upgrade the firmware selected.

SE59XX-SDK
Software development Kit
User Manual
V1.2
Note: This example is made with SE5901A. All other models of SE59XX family share the same method.
Figure 2.11 Firmware selection
Note that the extension file name of upgraded firmware should be .dld
2.4 Verify current firmware version
There are two methods to verify the fi rmware version:
1) Use a debug line as pe r Par agra ph 2.3 .1 above to connect console por t of the device. Afte r boot up, ty pe
“a top_show_ver” in the console command line to check curr ent version as Figure 1-13 shown. The red
rectangle shows information of boot-loader (V1.00), Ke rnel ( V1.00) and AP (V1.00) version number .
Figure 2.12 Fi rmware version - Console
2) Use Device Manager or Device Management Utility (Se rial Manager ) to check version number as pe r
Figure 2.13 . (Device Manager is currently su p por ted to Simplified Chinese release )