Sparkpad SCD15 User Manual

User Manual

(for Developers)

Updated: Nov 7, 2010

Sparkpad LLC CONFIDENTIAL

Sparkpad Platform Development Guide 11/27/2010

© Copyright 2010 Sparkpad LLC All rights reserved.

This document contains valuable confidential and proprietary information of Sparkpad LLC. No part of this documentation
may be transmitted or distributed, or copied, photocopied, scanned, reproduced, translated, microfilmed, or otherwise
duplicated on any medium without written consent of Sparkpad LLC. If written consent is given, the same confidential,
proprietary, and copyright notices must be affixed to any permitted copies as were affixed to the original.

Use of the software programs described herein and this documentation is subject to applicable terms of service and license
agreements. Unless specifically otherwise agreed in writing, all rights, title, and interest to this software and documentation
remain with Sparkpad LLC.

Information in this documentation has been carefully checked and is believed to be accurate. However, this information is
subject to change without notice, and Sparkpad LLC assumes no responsibility for any inaccuracies that may be contained
in this documentation. In no event will Sparkpad LLC be liable for direct, indirect, special, incidental, or consequential
damages resulting from any defect or omission in this technical note, even if advised of the possibility of such damages.

In the interest of continued product development, Sparkpad LLC reserves the right to make improvements to this
documentation and the products it describes at any time, without notice or obligation.

The trademarks, logos, and service marks ("Marks") displayed in this document are the property of Sparkpad LLC or other
third parties. You are not permitted to use the Marks without the prior written consent of Sparkpad LLC or such third party
which may own the Marks. "Sparkpad LLC," "Sparkpad," and iGala are registered trademarks of Sparkpad LLC

Published by

Sparkpad LLC
46090 Lake Center Plaza, #206
Sterling, Virginia 20165
Phone: [phone]
Fax: [phone]

Printed in the United States of America

Sparkpad LLC CONFIDENTIAL 2

Sparkpad Platform Development Guide 11/27/2010

Table of Contents

Platform Development Guide Error! Bookmark not defined.

Table of Contents 3

1. Introduction 5

1.1. Conventions 5

1.2. System architecture 6

2. LUA application development 9

2.1. Overview 9

2.2. Running applications on a PC 10

2.3. Installing applications on a Sparkpad Device 11

2.4. Application invocation 12

2.5. Access Linux shell 15

2.6. Network setup 15

2.7. Touch screen, remote controls & more 16

2.8. LUA programming 16

2.8.1. File listing 16

2.8.2. How to create a screen with buttons 18

2.8.3. How to parse an XML file 25

2.8.4. How to enable automatic remote firmware update 26

2.8.5. Wi-Fi connection: wlan.lua 29

2.8.6. Memory management 30

2.8.7. GUI 31

2.8.8. Audio Volume Control: music_manager.lua 41

2.8.9. Component: component.lua 41

Sparkpad LLC CONFIDENTIAL 3

Sparkpad Platform Development Guide 11/27/2010

2.9. Notes to application developers 69

Sparkpad LLC CONFIDENTIAL 4

Sparkpad Platform Development Guide 11/27/2010

1. Introduction

Sparkpad is a hardware and software platform solution developed by Sparkpad LLC for
companies or individuals seeking an embedded device that is easily customizable. The
Sparkpad platform offers various hardware options, including:

 TFT touch screen displays (7”, 8”, 10.1” & 10.4”)
 Non-touch screen (remote operated) displays (15” and above)
 “Video Box” (remote operated) for use with any monitor
 Networking support with both WiFi and Ethernet connections
 A complete Software Development Kit (SDK) and sample applications for creating

customized functionality and user interfaces (UI)

 Operating System layer access (Linux)
 A full-featured Emulation and Development Environment for Windows

The iGala Wireless Digital Picture Frame (www.igala.com) is an example of a working
commercial application developed on the Sparkpad platform.

This programming guide is intended for software engineers who plan to build customized
applications on the Sparkpad platform. It provides information on how to use Sparkpad to
develop application extensions and includes sample application code.

1.1. Conventions

The following font conventions are used:
Code: This font is used for any device-generated data such as program codes, web page

source code and/or log messages generated.

Sparkpad LLC CONFIDENTIAL 5

Sparkpad Platform Development Guide 11/27/2010

Screen
Size

Screen
Resolution

Screen
Ratio

Input
Type

DSP

Ethernet

WiFi
7”

800x480

16:9

Touch
Screen

Telechip
7901

USB Host
Port

Marvell
(integrated)

8”

800x600

4:3

Touch
Screen

RMI
Au1250

Optional
USB Host

Internal
USB
module

10.1”

800x480
1024x600

16:9

Touch
Screen

Telechip
8902

Included

Marvell
(integrated)

10.4”

800x600

4:3

Touch

Telechip

Included

Marvell

Var: Similar to code, but text in this font involves variable identifiers and must be
replaced by other meaningful data. There will be a description on how to replace those
identifiers when they are mentioned in the document. For example, the command-line
arguments:

{code} or {var}: Device-generated data enclosed by ‘{‘ ‘}’ indicates the data is optional.

1.2. System architecture

Sparkpad hardware is available in different hardware configurations, including screen
size. Some devices are even available without a screen. For each device there may be
differences in the core DSP, memory size, board configuration, and interface ports. The
following table lists Sparkpad‟s currently available (or soon-to-be available) hardware
configurations:

Sparkpad LLC CONFIDENTIAL 6

Sparkpad Platform Development Guide 11/27/2010

1024x768

Screen

8902

(integrated)

15”

1024x768

4:3

Remote
Control

Telechip
7901

Included

Marvell
(integrated)

42”

1080x1024

16:9

Touch
Screen

Telechip
8902

Included

Marvell
(integrated)

Video Box

HDMI &
Component
Video
Output

N/A
(No
screen)

Remote
Control

Telechip
8902

Included

Marvell
(integrated)

Video Box

HDMI &
Component
Video
Output

N/A
(No
screen)

Remote
Control

Broadcom

Included

Broadcom
(integrated)

All hardware options run a modified version of the Linux OS. On top of Linux, Sparkpad
provides three development options for applications: LUA, Flash (coming soon) and
Android (coming soon), as illustrated in the following stack chart:

Sparkpad LLC CONFIDENTIAL 7

Sparkpad Platform Development Guide 11/27/2010

DSP (Telechip 7901, Telechip 8902, or RMI Au1205)

Linux 2.6.28

Nano X

LUA

Gnash
Android 2.2

Flash

JAVA

LUA
App

Flash
App

Android

App

Sparkpad
Platform

Customize
Layer

Currently, this document only assists with the development LUA applications (with or
without NanoX). Please note that for non-touch screen models, such as the 15” and “box”
devices, the LUA layer is built directly on top of Linux without NanoX.

Sparkpad LLC CONFIDENTIAL 8

Sparkpad Platform Development Guide 11/27/2010

Operation System

Linux version 2.6.28

2. LUA application development

This section provides information on how to build applications on the Sparkpad platform
using the LUA programming language. Sparkpad provides a LUA-based emulator for your
Windows PC, so most development and testing of your application software can be
completed before loading it onto the final end hardware.

2.1. Overview

Sparkpad hardware features different DSPs that run Linux. The display driver is
configured to support digital LCD displays in their native resolutions. All models include at
least 1GB of flash memory and 128MB RAM (most include 256MB).

The flash memory is partitioned into two sections:

 Application partition mounted under /nand1 folder
 Content partition mounted under /nand2 folder

Note: Developers should monitor memory consumption during development. The Linux
system kernel uses about 15 - 20MB of RAM. The LUA layer handles its own memory
management and consumes about 40MB per pool allocation.

Once the system boots up, the application partition will be mounted. The content partition
is mounted in the background. Before using this partition, the application should c that the
content partition has been properly mounted by checking for the directory
/nand1/load+found. The system then checks for the existence of shell scripts with the
name “igala_api.sh” under /nand1/config, and runs it automatically.

The development environment is structured as follows:

Sparkpad LLC CONFIDENTIAL 9

Sparkpad Platform Development Guide 11/27/2010

GCC

Version 4.1.2

UI

Microwindow nano-X 0.91

Programming Language

LUA

The following drivers are supported:

 LCD display
 Touch-Screen
 Wi-Fi 802.11b/g
 Ethernet
 USB host
 SD Card

2.2. Running applications on a PC

Applications developed for the Sparkpad platform using LUA can be run on any Windows
PC (without the need of a Sparkpad hardware device) using the provided emulator.
Developers can copy the application directory /nand1/bin to Windows and initiate the
application from a Windows command terminal (cmd) using command:

lua.exe app.lua

In this case, the name of the LUA application file is app.lua, which can be replaced with
any other LUA application files.

For standard Sparkpad applications, there is often a background process of fetching
network data from online servers with the name of nettask.lua. To completely emulate the
applications, the developer needs to initiate both the app.lua and nettask.lua processes
from two separate windows command terminals.

Sparkpad LLC CONFIDENTIAL 10

Sparkpad Platform Development Guide 11/27/2010

2.3. Installing applications on a Sparkpad Device

Once application development is completed in the PC emulation environment, developers
can use a USB flash drive or SD memory card to load their application onto the actual
device.

To install applications to a device, copy the following update.sh file and the zipped bin
directory bin.zip to the root directory of either a USB flash drive or SD memory card
and insert it into the respective port on the device. Lastly, power on the device. The
system will execute the update.sh file automatically.

Sample of update.sh

if [ -f "/mnt/SD/bin.zip" ]; then

unzip -o /mnt/SD/bin.zip -d /nand1/config

mv -f /mnt/SD/bin.zip /mnt/SD/updated_bin.zip

echo 3 > /proc/sys/vm/drop_caches

cd /nand1/

if [ -d "bin" ]; then

rm -f -r /nand1/bin

mv -f /nand1/config/bin /nand1

fi

fi

if [ -f "/mnt/OHCI/bin.zip" ]; then

unzip -o /mnt/OHCI/bin.zip -d /nand1/config

mv -f /mnt/OHCI/bin.zip /mnt/OHCI/updated_bin.zip

echo 3 > /proc/sys/vm/drop_caches

cd /nand1/

Sparkpad LLC CONFIDENTIAL 11

Sparkpad Platform Development Guide 11/27/2010

if [ -d "bin" ]; then

rm -f -r /nand1/bin

mv -f /nand1/config/bin /nand1

fi

fi

mkdir -p /nand2/bones/flash/abies

cp -af /nand1/bin/mnt/* /nand2/bones

cd /nand2/bones/flash/abies

mkdir -p photo/net/picasa

cd /nand1/bin

cp igala_api.sh /nand1/config

When the install process is complete, the device will restart.
Note that bin.zip is renamed automatically upon completion of the install process. This

ensures that the device will not be updated again if the developer has not yet removed
the USB flash drive or SD card.

Developers can rename or rearrange the network download content in the sample
application, as needed, located under /nand2/bones/flash/abies/photo/net/picasa.

2.4. Application invocation

Within the update.sh script, the file igala_api.sh is copied to the /nand1/config
folder. When the system boots up, this file will run automatically.

Sample of igala_api.sh

if [ -f "/mnt/SD/bin.zip" ] && [ -f "/mnt/SD/update.sh" ]; then

cd /nand1/bin

Sparkpad LLC CONFIDENTIAL 12

Sparkpad Platform Development Guide 11/27/2010

./lua update_info.lua

aplay -B 4096 frameworks/frameImages/alert.wav

cd /mnt/SD

chmod +x update.sh

./update.sh

mv update.sh update_pre.sh

reboot

fi

sleep 3

if [ -f "/mnt/OHCI/bin.zip" ] && [ -f "/mnt/OHCI/update.sh" ]; then

cd /nand1/bin

./lua update_info.lua

aplay -B 4096 frameworks/frameImages/alert.wav

cd /mnt/OHCI

chmod +x update.sh

./update.sh

mv update.sh update_pre.sh

reboot

fi

####remote update####

if [ -f "/nand1/bin/update.sh" ]

then

rm -f /nand1/bin/update.sh

fi

if [ -f "/nand1/bin.zip" ]

then

unzip -o /nand1/bin.zip -d /nand1

rm -f /nand1/bin.zip

echo 3 > /proc/sys/vm/drop_caches

if [ -f "/nand1/bin/update.sh" ]

Sparkpad LLC CONFIDENTIAL 13

Sparkpad Platform Development Guide 11/27/2010

then

cd /nand1/bin

chmod +x update.sh

./update.sh

fi

rm -f /nand1/bin/update.sh

echo 3 > /proc/sys/vm/drop_caches

fi

cd /nand1/bin

chmod +x ln.sh

chmod +x lua_8

chmod +x lua

chmod +x alert_play.sh

./ln.sh

./lua_8 nettask.lua&

sleep 2

./lua app.lua&

./lua_monitor&

Telnetd&

The first two sections of the if-fi code are to trigger the update process from USB/SD
card, if present. The script starts the following three Sparkpad processes and the telnet
daemon:

app.lua – Rendering of all UI
nettask.lua – Performs all network download activities
lua_monitor.lua – Monitors the health of application and nettask processes

Sparkpad LLC CONFIDENTIAL 14

Sparkpad Platform Development Guide 11/27/2010

2.5. Access Linux shell

The OS shell on the frame can be accessed only after the WiFi or Ethernet connection
has been configured and is running. From a Telnet client on a computer connected via the
same network, run:

telnet {IP address of the device, such as 192.168.0.102}

The shell access account is root/Udo. If successful, it will enter the Linux shell on the
frame. You can run any shell script command to debug your application.

2.6. Network setup

Developers can manually set up the network using LUA code, or from a shell command
line, using the following commands:

Ethernet:

 Ifconfig eth0 {IP address like 192.168.0.102}

WiFi:

 insmod /lib/modules/sd8686.ko
 iwconfig eth1 essid “{SSID of the wifi network}”
 ifconfig eth1 {IP address like 192.168.0.102}

Please note: For both WiFi and Ethernet, the previously established network must be
disconnected before a new network attempt is attempted.

Sparkpad LLC CONFIDENTIAL 15

Sparkpad Platform Development Guide 11/27/2010

2.7. Touch screen, remote controls & more

To be provided. Please contact [e-mail] meanwhile with questions.

2.8. LUA programming

This section describes how to develop a Sparkpad application using the LUA scripting
language.

The Sparkpad SDK includes a LUA executable for both Windows PC and the hardware
device. Developers can execute their LUA applications with commands such as
“lua.exe app.lua” in Windows PC environment and get the exact same application
behavior as they would on an actual Sparkpad hardware device. (One important
exception: the emulator borrows the network connection from the PC and thus the
network configuration process does not reflect the true experience on an actual device.)

Sparkpad strongly recommends that developers who are new to the platform begin by
attempting to modify top-layer LUA application code, as provided with the SDK. All
interactions with devices, such as the Wi-Fi module and the USB port, are handled in the
provided application. The encrypted LUA files come with the Core Application code are
compiled LUA codes

2.8.1. File listing

Directory Calendar (Touch screen only)
Directory frameworks
Directory mnt
Directory sdk

Sparkpad LLC CONFIDENTIAL 16

Sparkpad Platform Development Guide 11/27/2010

app_bone.lua

Main entry of Sparkpad LUA Bones Application (Touch screen only)
do_calendar.lua
do_gmail.lua
do_picasa.lua
fpDisplay.lua
fpFrequency.lua
fpGmail.lua
fpPicasa.lua
fpPicasaAlbum.lua
fpPowerSave.lua
fpTransition.lua
fpWifi.lua
fpWifiKeyboard.lua
fpWifiType.lua
fsCalendar.lua
fsMainMenu.lua
fsMedia.lua
fsSetup.lua
gmail.lua
gmail_setup.lua

Sparkpad LLC CONFIDENTIAL 17

Sparkpad Platform Development Guide 11/27/2010

media_manager.lua
nettask.lua
picasa.lua
playlist.lua
setting.lua
system_manager.lua
videoplay.lua
wlan.lua
wlan_check.lua

2.8.2. How to create a screen with buttons

The following example shows how to create a screen with buttons.

function create(scene, back_page)

local page = glyph.glyph(scene,0,0,1024,768) -- 15 inch screen

resolution here

local page_title = component.text(page, 'Title here',

gui.WHITE,nil,font_factory.load('frameworks/font/arial.ttf',

50),bit._or(glyph.Alignment.hcenter, glyph.Alignment.vcenter))

page_title:hcenter()

page_title:offset(0, 20)

local function create_buttons(parent, ...)

local push_arg = {

parent = parent,

color = gui.WHITE,--WHITE,

Sparkpad LLC CONFIDENTIAL 18

Sparkpad Platform Development Guide 11/27/2010

image =

'frameworks/frameImages/blue_button_extra_big.png',

caption = 'button',

alignment = bit._or(glyph.Alignment.hleft,

glyph.Alignment.vcenter),

font = font_factory.load('frameworks/font/arial.ttf',

21),

no_auto_pop=true

}

local ret ={}

local y = 200

for _, f in ipairs(arg) do

push_arg.caption = f

ret[#ret + 1] =

component.push_button(component.push_button_arg(push_arg))

ret[#ret]:move(200, y)

y = y + 60

end

return ret

end

local button = {}

button = create_buttons(page, "button text here")

local zone_list = {

{-6, " (UTC-06:00) Central Time (US & Canada)"},

{-5, " (UTC-05:00) Eastern Time (US & Canada)"},

{-4, " (UTC-04:00) Atlantic Time (Canada)"},

{-3, " (UTC-03:00) Buenos Aires"},

Sparkpad LLC CONFIDENTIAL 19

Sparkpad Platform Development Guide 11/27/2010

{-2, " (UTC-02:00) Mid-Atlantic"},

{-1, " (UTC-01:00) Cape Verde Is."},

{-12, " (UTC-12:00) International Date Line West"},

{-11, " (UTC-11:00) Midway Island, Samoa"},

{-10, " (UTC-10:00) Hawaii"},

{-9, " (UTC-09:00) Alaska"},

{-8, " (UTC-08:00) Pacific Time (US & Canada)"},

{-7, " (UTC-07:00) Mountain Time (US & Canada)"},

{0, " (UTC) GMT : Dublin, Edinburgh, Lisbon, London"},

{1, " (UTC+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm,

Vienna"},

{2, " (UTC+02:00) Athens, Bucharest, Istanbul"},

{3, " (UTC+03:00) Moscow, St. Petersburg, Volgograd "},

{4, " (UTC+04:00) Caucasus Standard Time"},

{5, " (UTC+05:00) Islamabad, Karachi"},

{6, " (UTC+06:00) Almaty, Novosibirsk"},

{7, " (UTC+07:00) Bangkok, Hanoi, Jakarta"},

{8, " (UTC+08:00) Kuala Lumpur, Singapore"},

{9, " (UTC+09:00) Osaka, Sapporo, Tokyo"},

{10, " (UTC+10:00) Canberra, Melbourne, Sydney"},

{11, " (UTC+11:00) Magadan, Solomon Is., New Caledonia"},

{12, " (UTC+12:00) Auckland, Wellington"},

}

local txt = component.text(page,'Current:',

gui.WHITE,nil,font_factory.load('frameworks/font/arial.ttf',

25),bit._or(glyph.Alignment.hleft, glyph.Alignment.vcenter))

txt:move(200,100)

local txt_next_caption = component.text(page,' ',

gui.WHITE,nil,nil,bit._or(glyph.Alignment.hleft,

glyph.Alignment.vcenter))

Sparkpad LLC CONFIDENTIAL 20

Sparkpad Platform Development Guide 11/27/2010

txt_next_caption:move(300, 100)

txt_next_caption:set_caption(setting.abies_config.zonetime[1

])

local argu = {

parent = page,

caption = ' ',

image = 'frameworks/frameImages/blue_triangle_left.png',

color = gui.WHITE

}

local prebtn =

component.push_button(component.push_button_arg(argu))

argu.image = 'frameworks/frameImages/blue_triangle_right.png'

local nextbtn =

component.push_button(component.push_button_arg(argu))

argu.image = 'frameworks/frameImages/green_button_small.png'

argu.caption = 'Done'

argu.font = font_factory.load('frameworks/font/arial.ttf', 30)

local done =

component.push_button(component.push_button_arg(argu))

prebtn:move(200, 600)

layout.in_row_center(prebtn,{done, nextbtn}, 100)

function button_caption(current_zone, pre_zone)

local zone = (current_zone - pre_zone) * 3600

local real_hour

local os_time_year, os_time_month, os_time_date,

os_time_hour, os_time_minute, os_time_noon =

time_manager.get_time()

if os_time_noon == "PM" and tonumber(os_time_hour) ~= 12 then

real_hour = os_time_hour + 12

Sparkpad LLC CONFIDENTIAL 21

Sparkpad Platform Development Guide 11/27/2010

else

real_hour = os_time_hour

end

if setting.abies_config.daylight_config["dst"] == 1 then

real_hour = real_hour - 1

end

local changetime = os.time{year = os_time_year, month =

os_time_month, day = os_time_date, hour = real_hour, min =

os_time_minute,isdst =

setting.abies_config.daylight_config["dst"]}

local real_time = changetime + zone

local d = os.date("*t",real_time)

if constant.WIN32 then

os.execute("date " .. d.year .."-".. d.month .."-"..

d.day )

os.execute("time " .. d.hour ..":".. d.min ..":".. d.sec )

else

os.execute("date -s \"" .. d.year .. "-" .. d.month .. "-" ..

d.day .. " " .. d.hour .. ":" .. d.min .. ":" .. d.sec .. "\"")

end

end

local flag = 0

local index = 0

local function click_zone(i)

return function()

windows:add( function()

setting.load(setting.abies_config)

local zone_pre = setting.abies_config.zonetime[2]

Sparkpad LLC CONFIDENTIAL 22