MCVU 2017 – Application 2

TinyOS Annoying Lunar Landerv1.1

Version Date Remark

1.1 Jun 13, 2017 Update of scoreboard Interface
1.0 May 22, 2017 Initial release

Contents
1 General Remarks 2

2 High-Level Specification 2
2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1.1 Ethernet Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.2 MP3 Decoder/SD-Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.3 Potentiometer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.4 GLCD & Touchscreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.5 2x16 LCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.6 PS/2 interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.7 Compass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Detailed Specification 5
3.1 TerrainGeneratorC (TerrainGenerator ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2 GamePadC (GamePad ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.3 PhysicsC (Physics) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.4 PS2C (PS2 ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.5 VolumeAdcC (Read ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.6 HplVS1011eC (HplVS1011e) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.7 VS1011eC (MP3 ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.8 SdcardC (Sdcard ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.9 TouchscreenC (Glcd, TouchScreen) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.10 TimerMilliC (Timer ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.11 BufferedLcdC (BufferedLcd ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.12 UdpC (UdpSend, UdpReceive) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.13 RandomAdcC (Read ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.14 RandomC (Random, ParameterInit) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.15 ScoreC (Score, Init) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4 Theory Tasks 16

5 Demonstration and Protocol 17

5.1 Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6 Grading 18

1
1 General Remarks
Before you start working on the application be sure that you are familiar with TinyOS.
We provide a TinyOS repository for this course in the TILAB , which you can clone with git clone
ssh://ssh.tilab.tuwien.ac.at/opt/mcvl/tinyos ss17.git. When you need to change files from the
TinyOS system, you need to copy them into your application directory and change them there. This
makes it a lot easier to apply future updates of TinyOS, if need be. It also makes submitting your
application much easier as you only have to submit one folder, which is also the only thing supported
by our Makefile. From time to time you should check for updates in the repository (when we release
bugfixes): Use git pull to update to the latest version. You will find the template for this application
located in the repository under the folder apps ecs/lunar lander.
No specification is complete! Design decisions have to be documented in the protocol.
Please note that if you want to receive bonus points for additional work, you have to state in the
protocol which parts you think are eligible for bonus points and why. Bonus points are awarded on a
case by case basis and there is no right for bonus points.
Please recall that bonus point only improve a positive grade and cannot help you pass the course.
Therefore, please add fancy stuff only after you have finished the basic assignment.

2 High-Level Specification
You have to implement a lunar lander clone, based on the TinyOS operating system. The gameplay has
to be controllable via an accelerometer located on the CompassClick add-on board. The player can set
their name via a PS/2 keyboard. Additionally, a network-based scoreboard has to be informed about
the achieved points of a player.
The mp3-board should be used to provide background music during gameplay, and may also play
sound effects. The volume of the music should be controllable via the potentiometer.
Over the ethernet board, your application has to respond correctly to ICMP Echo requests, and
properly refuse all other UDP packets (ICMP destination unreachable).
The PC has the static IP address 10.60.0.1 and the application should have the static IP address
10.60.0.10. The subnet mask is 255.255.255.0. On the PC, a scoreboard software, available on the course
homepage, can be run. This tool can be interacted with to have a highscore for the game.

2.1 Overview
The external interfaces of the lunar lander are shown in Figure 1. These are the “connections to the real
world” of the microcontroller application. They consist of the following elements:

Touchscreen

2x16 LCD GLCD

Digital O Analog I Dig. I/O

PS/2 Keyboard Digital I/O Analog I Potentiometer

Lunar Lander
Digital I
Compass I2C
SPI SD-Card

Int. Dig. I/O SPI Dig. I/O Int.

Ethernet MP3 Decoder

Figure 1: Lunar Lander – External Interfaces

2
2.1.1 Ethernet Module
We are using the MikroElektronika Serial Ethernet Board [1] connected to the bigAVR6 development
board via SPI. This extension board features the Microchip ENC28j60 Ethernet controller [2] which
completely implements the physical, as well as the MAC layer, for a 10BASE-T Ethernet connection.
The wire connections between the extension board and the development board are shown in Table 1.

Serial Ethernet bigAVR6

CS PB0
SCK PB1
MOSI PB2
MISO PB3
RST PB4
INT PD2
VCC VCC
GND GND

Table 1: Connection plan of the Serial Ethernet extension

Note
You have to ensure that the dip switches for the on-board SD Card reader on SW15 are turned
off to correctly receive data from a module over SPI. You should always use the SD Card slot on
the SmartMP3 add-on board and disconnect the onboard slot via the according DIP switches on
SW15. The reason for this is that the onboard slot drives the MISO line even if the chip-select is
disabled and thus prevents all other communication on the bus.

Note
To allow for debugging of the network protocol, we have installed wireshark in the lab. You can
use it by running wireshark-p3p1.
Debugging via printf is also available, checkout the Printf and UartAndPrintf demo. In the lab
you can use, e.g., minicom by running minicom -o -D /dev/ttyS0 -b 115200. On some PCs
you may need to change the port to /dev/ttyS1! Note that printf uses UART1 which can be
connected to B Port on SW13.

2.1.2 MP3 Decoder/SD-Card

The chips are connected to the ATmega via SPI using the USART module. This is required as, due to
a hardware design decision, the SD-Card reader and the Ethernet board always drive the MISO line. If
you connect the MISO line of the SmartMP3 extension board to the Ethernet board, you are not able
to read data from either one!
The wire connections between the extension board and the development board are shown in Table 2.

SD Card
The SD Card stores a collection of sound files. You can choose to use one or more files in your application.
A detailed document with the list of sound files, and their alignment on the card, is available on the
course homepage [3]. The sounds are stored as raw data on the SD Card, i.e., there is no file system.

SD Card Block Access: (Read) Access to the SD Card is done in data blocks with a length of 32 bytes.
This part is provided as a component to you. While the component reads the card blockwise, it
expects the read offset as byte address. Despite this fact, all read access must be block-aligned.
The component also handles the initialization of the SD Card which has to be done at a lower
speed than the actual read access.

3
 SmartMP3 bigAVR6
MISO PJ0
SPI MOSI PJ1
SCK PJ2
MMC CS PF4
SD Card
MMC CD PF5
BSYNC PF3
MP3 CS PF6
MP3
MP3 RST PF7
DREQ PJ3
VCC VCC
Power
GND GND

Table 2: Connection plan of the SmartMP3 extension board

SPI: Low level access to the card is done via SPI, and is already implemented in TinyOS.
Pinout: The SD Card slot on the SmartMP3 extension should be attached to the bigAVR6 board using
the pins shown in Table 2.

Hint
While all students should use the same pinout, it is always a good idea to check the connections
when (re)starting to work in the lab. This can dramatically reduce the debugging needs of a
program which “worked the last time”.

MP3 Decoder
We use the VS1011e MP3 Audio Decoder on the MikroElektronika SmartMP3 add-on board [4] which has
a quite extensive datasheet [5]. We provide a component which handles the set-up and communication
with the decoder. You just have to implement a component which abstracts the data transmission and
access to the configuration of the module. The connection plan is shown in Table 2.

2.1.3 Potentiometer
The volume should be adjustable by turning the potentiometer P5 on the bigAVR6 board connected to
the ADC. When turning the potentiometer clockwise, the volume should increase. Use ADC Channel 2
as input and try to approximate a linear loudness scale.

Hint
The function 1 − (1 − x)4 , x ∈ [0, 1] is a good approximation and can be implemented using 16-bit
integer arithmetic (scale wisely).

Please also note that, when the volume is turned up very high, the SmartMP3 board can use more
power than certain USB ports can provide. Therefore, if you notice multiple resets of the controller while
music playback is active, it might help to reduce the volume (which your lab colleagues will favor) or to
use an external power supply.

2.1.4 GLCD & Touchscreen

The GLCD provides the main interface for the game. While there are no specific guidelines on the look
of your game, orienting it around Atari’s Lunar Lander should be the goal. This also includes the zoom
into the gamefield on proximity to the ground. The zoom should at least halve the currently displayed

4
height, and the landscape should be not higher than 3/4 of the screen in zoomed mode. Unzoomed at
least 80 m should be displayed on the screen.
The GLCD is connected via the designated mounting frame to the bigAVR6.
To enable the GLCD and the touchscreen you have to enable the dip switches 1–4 on SW13 as well
as dip switch 8 on SW15. The voltage reference jumper J18 should be set to VCC, and touchscreen
connector has to be placed into the corresponding connector CN22.

Note
Please do not remove the touchscreen’s cable from the connector. They are easy to yank off the
screen and if they are, the screen has to be replaced.

2.1.5 2x16 LCD

During gameplay, this alphanumeric LC-Display has the purpose to display the remaining fuel, the
height above ground, the current velocity vector (separated into horizontal and vertical), and the degree
disparity between the lander’s current orientation and the gravity vector.
The LC-Display is connected via the designated mounting frame to the bigAVR6.

2.1.6 PS/2 interface

The game should allow the player to enter his nickname, for the high score, via a standard PS/2 keyboard.
You may also allow the player to use certain keys to control the game.
To connect the Mini-DIN connector of the keyboard to your boards, you have to use the Easy PS2
add-on board. In order to also connect the I2C and the Ethernet interrupt pin, you are also advised
to use the Easy Test wiring board to duplicate the PORTD pin header. On the Easy PS2, setup the
DIP-switches as listed in Table 3 (set all other switches to Off ).

Signal Pin
CLK C7 (=PK7)
DATA D6 (=PK6)

Table 3: Configuration of the PS/2 extension board

2.1.7 Compass
Slightly contrary to its name, the Compass Click provides access to a accelerometer. The accelerometer
is used to control the lunar lander. To access the LSM303DLHC chip on this module, I2C/TWI is used.
As the LSM303DLHC works with 3.3 V, contrary to the 5 V the bigAVR6 uses, a level conversion is
required. Due to the bidirectional design of the I2C, a more elaborate solution as described in [6] has to
be used.1 We will setup the breadboards in the lab correctly and wire it to the EasyConnect. You only
have to ensure that the EasyConnect is connected to PORTD via an EasyTest.

3 Detailed Specification
A proposal for the TinyOS modules used in the application is shown in Figure 2. Square boxes mark
configurations/modules while elliptic nodes denote interfaces. The modules filled in orange have to be
implemented by you, while the white modules are already provided by us respectively included in TinyOS.
Note that the interface proposal is not complete as, depending on your implementation, you might need
additional modules and there might be other modules below the ones that are shown. In fact you will
have to alter some modules to implement the network functionality as requested by the specification.
You can also change some module dependencies if they are useful, e.g., integrating PS2 and GamePad
into a module GameInput might simplify things.
1 If this design would be used on the mp3- and the ethernet-board, they could share the same SPI bus.

5
 LunarLanderAppC

GamePad TerrrainGenerator PS2 MP3 Touchscreen Glcd BufferedLcd Timer

GamePadC TerrrainGeneratorC PS2C VS1011eC Physics TouchscreenC BufferedLcdC TimerMilliC Init

ParameterInit HplAtmegaPinChange Sdcard

HplVS1011e Read<uint16 t> Score
Random
Atm128I2CMasterC HplAtmegaPinChange2C SdcardC

ScoreC
RandomC GeneralIO PhysicsC VolumeAdcC

6
Read<uint16 t> Timer HplAtm1280GeneralIOC UdpReceive
GeneralIO ResourceConfigure

HplVS1011eC
TimerMilliC Read<uint16 t> Atm1280AdcConfig
UdpSend
RandomAdcC
AdcReadClientC

HplAtm1280GeneralIOC
GeneralIO ResourceConfigure
UdpC

Read<uint16 t> Atm1280AdcConfig

AdcReadClientC

HplAtm1280GeneralIOC

Figure 2: Proposed interface architecture for the Annoying Lunar Lander

 Note
The GLCD is wired by TouchscreenC. If you do not intend to utilize the touchscreen, you can
just directly wire the GLCD.

The modules are explained in the following:

3.1 TerrainGeneratorC (TerrainGenerator )

This module generates a random landscape for the game by sampling random bits from the module Ran-
domC.
We do not provide you with a guideline on how to generate such a terrain, yet a simple solution will
suffice. In the spirit of the computer game Lunar Lander by Atari, landing is only possible on plane
surfaces. Therefore, you have to ensure that there are (at least some) plane surfaces with a sufficient
length so that landing is possible. That is, if your algorithm normally produces such terrains, it is fine.
Otherwise, this has to be ensure algorithmically. Also, the terrain generated has to have at least three
different inclination angles (plane, up, and down).

3.2 GamePadC (GamePad )

This module interfaces with the LSM303DLHC on the Compass Click add-on module via I2C. It shall
initialize the chip on boot and provide the accelerometer information over the interface GamePad listed
in Listing 1. The interface has the same semantic as the interface Read<>.
The I2C communication with the chip is abstracted by the module Atm128I2CMasterC. Detailed
information on the specifics of the chip can be found in [7].
To work with the chip, we recommend to first reset it by setting the bit BOOT in the regis-
ter CTRL REG5 A. Following this, enable a sampling with 50 Hz of the x- and y-axis via register
CTRL REG1 A. After that, you can read the corresponding accelerometer values, e.g., for the x-axis,
from the registers OUT X L A and OUT X H A.

Hint
The chip has an auto-increment functionality.

interface GamePad {

command void request linear accel(void);

async event void linear accel ready(int16 t x acc, int16 t y acc);

}

Listing 1: GamePad

3.3 PhysicsC (Physics)

This module provides the game physics for the application by step-wise evaluation of a differential
equation. Table 4 provides an overview of the constants involved in the physics simulation required.
Furthermore, Table 5 lists the variables used in the pseudo-code given in Algorithm 1, where the two
time-dependent variables are user inputs. Note that, in the algorithm a vector is denoted as v with its
components being vx resp. vy .
The constants are based on the actual Apollo lunar lander, and have been collected from [8, 9]! This
means that the should work just fine, small adaptations to improve gameplay are allowed. Yet, at some
point you need to convert from meter into pixels.
Please recall that you are not allowed to use floating-point operations. We had good experience with
a fixed-point Q10.5 (one sign bit, 10 integer bits, and 5 fractional bits). For calculation the sinus (and
cosines) you will have to resort to a look-up table. Keep in mind that the microcontroller works on base
2, fix point arithmetic is not a “simple” scaling by 10x , but by 2x .

7
 Constant Value Description
m0 16 400 kg initial mass of the lander
fmax 8200 kg the initial amount of fuel of the lander
v0 (100, 0) m/s initial velocity of the lander
h0 (1,0) initial heading of the lander
p0 implementation dependent initial position of the lander.
Tmax 45 050 N maximum thrust the lander can produce
ṁ 208 kg/s mass flow rate of the lander’s engine.
g` 1.625 m/s2 lunar gravity
ω 0.125 rad/s maximal angular velocity

Table 4: Constants for lunar lander

variable description
t the current simulation time.
α(t) rotation change at time t [−1, 1].
th(t) throttle position at time t, [0, 10 . . . 60]%
m mass of the lander
v velocity of the lander
a acceleration of the lander
h heading of the lander
o orientation vector of the lander
θ orientation of the lander in degree
t thrust vector of the lander
p position of the lander

Table 5: Variables used in lunar lander

Hint
It might be advantageous to develop and test the physic-related computations on a PC, where
debugging is much easier.
Plotting the output of your calculations can be quite useful, and fitting tool are installed in the
lab, e.g., gnuplot, or R.

Note
You a not required to implement the simulation as stated, but the general behavior has to be the
same. E.g., rearrange/optimize some calculations/constants to the improve performance.

Conditions for a safe landing Obviously, the lander has certain restrictions for a safe landing listed
below:
• The landing area has to be plane.

• The angle between the gravity vector and the orientation vector of the lander has to be 6 6◦ .
• The vertical velocity (towards the ground) has to be below 3.65 m/s.
• The horizontal velocity has to be below 1.82 m/s. If vertical velocity is below 1.52 m/s, a horizontal
velocity of 2.44 m/s is allowed.

8
 m = m0 ;
v = v0 ;
h = h0 ;
p = p0 ;
t = 0;
while not (crashed or landed) do
wait ∆T ;
t = t + ∆T ;
t = −o;
ax = Tmax ·th(t)·t
m
x
;
Tmax ·th(t)·ty
ay = m + g` ;
v = v + ∆T · a;
p = p + ∆T · v;
m = m − ṁ · th(t);
θ = θ + α(t) · ω · ∆T ;
ox = ox · cos(θ) − oy · sin(θ);
oy = ox · sin(θ) + oy · cos(θ);
end
Algorithm 1: Simulation of the behavior of the lunar lander above the surface with a step size of ∆T .

3.4 PS2C (PS2 )

The PS2 module uses the HplAtm1280GeneralIOC and HplAtm128InterruptC interfaces to set up its
input pins and install an ISR for handling the clock generated by the keyboard’s controller.
For every pressed key the keyboard generates so called scancodes. These scancodes then need to be
translated into a corresponding ASCII character. As soon as the reception of one character is completed,
the corresponding event should be fired to signal the received character to the main application. You do
not need to fire an event for every character (e.g., escape), but alphanumerical input, upper/lower case,
and deletion must be supported.
Atmel Application Note 313 [10] includes a scancode-to-ASCII mapping, and may provide you with
some ideas on how to implement the interfacing of the PS/2 keyboard to the microcontroller. Note that
the code in the application note might not be the most efficient, or even easiest to implement for that
matter.
interface PS2 {

/∗∗
∗ Init Pins, enable IRQ
∗/
command void init(void);

/∗∗
∗ Fired when a character has been entered on the keyboard
∗
∗ @param chr ASCII value of the character entered
∗/
async event void receivedChar(uint8 t chr);

Listing 2: PS2

3.5 VolumeAdcC (Read )

The module VolumeAdcC provides the interface Read<uint16 t> and handles the access to the ADC
for the volume adjustment of the MP3 playback. The provided interface is a TinyOS standard interface
and can be redirected directly to the module AdcReadClientC which also handles the arbitration for
the hardware access. Additionally, the module AdcReadClientC uses the interfaces Atm1280AdcConfig

9
and ResouceConfigure, to trigger the pin setup after the ADC access is granted. The pin access should
be done by using the interface GeneralIO provided by the module HplAtm1280GeneralIOC for all
pins.

Hint
All interfaces used by this module are defined by TinyOS. While hardware independent interfaces
usually can be found in “tos/interfaces” the hardware dependent interfaces (and their enum decla-
rations) usually can be found under a path resembling “tos/chips[ ecs]/theChip/[theFunction/]”.
Note that code can be inherited from other chips.
See “support/make/platforms/bigAVR6 1280.platform” for details about the code locations for our
platform.

3.6 HplVS1011eC (HplVS1011e)

This provided module handles the hardware access for the MP3 extension board. Using the mod-
ule Atm1280SpiC and its interfaces, it handles the SPI communication and, via the module Hpl-
Atm1280GeneralIOC, it manipulates the port pins. Since the data request of the MP3 board is con-
nected to PJ3, the module HplAtmegaPinChange1C has to be used to send data interrupt driven,
i.e., without any busy waiting. The module provides the interface HplVS1011e shown in the listing
below. The used interfaces can be found in the TinyOS source tree.
interface HplVS1011e {

/∗∗
∗ Init pins
∗/
command void init( void );

/∗∗
∗ Reset the VS1011e
∗/
command void reset( void );

/∗∗
∗ Set a VS1011e register to a given value
∗
∗ @param mp3Register Register to be written
∗ @param mp3Cmd Command to be written
∗
∗ @return SUCCESS if register write was requested successfully
∗/
command error t writeRegister( mp3 reg t mp3Register, uint16 t mp3Cmd );

/∗∗
∗ Notification that the register write completed
∗
∗ @param error SUCCESS if sending completed successfully
∗/
event void writeDone( error t error );

/∗∗
∗ Read a VS1011e register
∗
∗ @param mp3Register Register to be read
∗ @param value A point to a data buffer where the register content will be stored
∗
∗ @return SUCCESS if register read was requested successfully
∗/
command error t readRegister( mp3 reg t mp3Register, uint16 t ∗value );

/∗∗
∗ Notification that the register read completed
∗

10
 ∗ @param error SUCCESS if successfully
∗ @param value A point to a data buffer where the register content will be stored
∗/
event void readDone( error t error, uint16 t ∗value);

/∗∗
∗ Send data to the VS1011e
∗
∗ @param data A point to a data buffer where the data is stored. This
∗ buffer must be valid until sendDone gets signaled!
∗ @param len Length of the message to be sent − data must be at least as large as len
∗
∗ @return SUCCESS if request was granted and sending the data started
∗/
command error t sendData( uint8 t ∗data, uint8 t len );

/∗∗
∗ Notification that sending data completed
∗
∗ @param error SUCCESS if sending completed successfully
∗/
event void sendDone( error t error );

/∗∗
∗ Test if the VS1011e is ready to accept new data
∗
∗ @return FALSE if ready to accept new data
∗/
command bool isBusy( void );
}

Listing 3: HplVS1011e

3.7 VS1011eC (MP3 )

The module VS1011eC is the high-level driver for the MP3 decoder chip. It uses the interface
HplVS1011e provided by the hardware abstraction layer module explained in the previous subsection
and provides the interface MP3 to the application, as shown in the listing below. Additional information
can be found either in the libmp3 source [11] or the MP3 decoder programming howto [12]. The full
data sheet of the decoder chip [5] should not be needed for implementation and thus only listed for the
sake of completeness.
As the application reads the mp3-files from the sdcard.
interface MP3 {

/∗∗
∗ Start and stop sine test
∗
∗ @param on TRUE to start − FALSE to stop
∗
∗ @return SUCCESS if command was successfully sent over SPI
∗/
command error t sineTest( bool on );

/∗∗
∗ Set volume
∗
∗ @param volume Volume to be set
∗
∗ @return SUCCESS if command was successfully sent over SPI
∗/
command error t setVolume( uint8 t volume );

/∗∗
∗ Send data
∗
∗ @param data A point to a data buffer where the data is stored

11
 ∗ @param len Length of the message to be sent − data must be at least as large as len
∗
∗ @return SUCCESS if request was granted and sending the data started
∗/
command error t sendData( uint8 t ∗data, uint8 t len );

/∗∗
∗ Notification that sending data completed
∗
∗ @param error SUCCESS if sending completed successfully
∗/
event void sendDone( error t error );

/∗∗
∗ Check if VS1011e is ready to accept new data
∗
∗ @return FALSE if VS1011e is busy or sending of data is in progress − otherwise TRUE
∗/
command bool isBusy( void );
}

Listing 4: MP3

3.8 SdcardC (Sdcard )

The module SdcardC is the high-level driver for the SD-Card reader and is provided by us. The module
provides the interface Sdcard listed below to the application for accessing data stored on the SD-Card.
interface Sdcard {

/∗∗
∗ Initializes the SD−Card
∗/
command error t init();

/∗∗
∗ Fired upon completion of init()
∗/
event void initDone(error t error);

/∗∗
∗ Start a read of a block from the specificed address to the given
∗ buffer.
∗/
command error t readBlock(uint32 t byteAddr, uint8 t ∗buffer);

/∗∗
∗ Fired upon completion of readBlock command.
∗/
event void readBlockDone(uint8 t ∗buffer, error t error);

/∗∗
∗ Check if a SD−Card is present.
∗
∗ @return FALSE if no SD−Card is present
∗/
command bool inserted();
}

Listing 5: Sdcard

3.9 TouchscreenC (Glcd, TouchScreen)

The module TouchscreenC is provided by us and handles the output on the graphical LCD as well as
the input via the resistive touchscreen. For this reason, it provides two interfaces: Touchscreen described
in Listing 6 and Glcd partly described in Listing 7. The initialization of the module is directly wired to
the SoftwareInit stage of TinyOS.

12
 The command getCoordinates requires a pointer to a place where the module can put the result.
Please note that the data is only valid after the event coordinatesReady was triggered. For type
definition of the variable type ts coordinates t have a look at the corresponding header file. There is also
a demo in apps ecs that demonstrates the use of the touchscreen module.

Note
The touchscreen needs to be calibrated. Please be aware that these two constants depend on the
board. If you choose to add touchscreen UI, ensure that the “sensitive” areas are large enough to
also work on another board.

interface TouchScreen{

/∗∗
∗ Sets calibration offsets for the touchscreen
∗ @return SUCCESS
∗/
command error t calibrate( int8 t x offset, int8 t y offset );

/∗∗
∗ Triggers request for touch coordinates
∗ @param pointer to buffer for coordinates
∗ @return SUCCESS if request was accepted
∗ EBUSY if another request is pending
∗/
command error t getCoordinates( ts coordinates t ∗xy );

/∗∗
∗ Notification that coordinates are ready
∗/
event void coordinatesReady( void );
}

Listing 6: TouchScreen

interface Glcd{

/∗∗
∗ Set pixel
∗ @param x−coordinate
∗ @param y−coordinate
∗ @return SUCCESS
∗/
command error t setPixel(const uint8 t x, const uint8 t y);

/∗∗
∗ Clear pixel
∗ @param x−coordinate
∗ @param y−coordinate
∗ @return SUCCESS
∗/
command error t clearPixel(const uint8 t x, const uint8 t y);

/∗∗
∗ Invert pixel
∗ @param x−coordinate
∗ @param y−coordinate
∗ @return SUCCESS
∗/
command error t invertPixel(const uint8 t x, const uint8 t y);

/∗∗
∗ Draw line
∗ @param first point x
∗ @param first point y
∗ @param second point x
∗ @param second point y

13
 ∗ @return SUCCESS
∗/
command error t drawLine(const uint8 t x1, const uint8 t y1,
const uint8 t x2, const uint8 t y2);

/∗∗
∗ Draw rectangle
∗ @param upper left x
∗ @param upper left y
∗ @param lower right x
∗ @param lower right y
∗ @return SUCCESS
∗/
command error t drawRect(const uint8 t x1,const uint8 t y1,
const uint8 t x2,const uint8 t y2);

...

/∗∗
∗ drawText
∗ @param text
∗ @param x−coordinate of lower left edge
∗ @param y−coordinate of lower left edge
∗ @return SUCCESS
∗/
command void drawText(const char ∗text,
const uint8 t x, const uint8 t y);

/∗∗
∗ drawTextPgm
∗ @param text stored in program memory
∗ @param x−coordinate of lower left edge
∗ @param y−coordinate of lower left edge
∗ @return SUCCESS
∗/
command void drawTextPgm(const char ∗text,
const uint8 t x, const uint8 t y);
}

Listing 7: GLCD

3.10 TimerMilliC (Timer )

Provides the Timer interface you might need as system timer. For a detailed description of the timer
system in TinyOS please refer to the TinyOS documentation (especially the TinyOS programming manual
and for more in-depth information TEP 102).

3.11 BufferedLcdC (BufferedLcd )

The module BufferedLcdC is given by us and handles the output on the 2x16 character LCD. It
provides the interface BufferedLcd . The initialization of the module is directly wired to the SoftwareInit
stage of TinyOS. There is also a demo in apps ecs that demonstrates the use of the 2x16 LCD module.
interface BufferedLcd {

/∗∗
∗ @param period refresh period in ms,
∗ set to 0 to disable auto refresh
∗/
command void autoRefresh(uint32 t period);
command void clear();
command void write(char ∗string);
command void write P(prog char ∗string);
command void goTo(uint8 t line, uint8 t col);
command void forceRefresh();

14
 Listing 8: BufferedLcd

3.12 UdpC (UdpSend, UdpReceive)

This module is provided and implements the UDP communication. The module is a generic component
and takes a UDP port as parameter on initialization. The module provides the interface UdpReceive,
using the UDP port from the initialization as listen port, as well as the interface UdpSend , using the
same UDP port as sender port. It is possible to instantiate this component and only wire the receive
interface and it is also possible to only wire the send interface. Furthermore, it is possible to use multiple
instances of the component in the same module (but with different port parameters).
There is a demo in the apps ecs folder demonstrating the use of the network stack.
To implement the whole functionality of the application you have to dig into the network stack so
you can implement the ICMP echo reply as well as the proper rejection of UDP packets received on ports
on which no module listens. If you are changing something inside the network stack, please ensure that
you copy the necessary file(s) into your application and make the changes there and not directly inside
the provided module as stated in the general remarks at the beginning of this document.

Note
For implementing the additional functionality you have to dig a little into the network stack and
you have to know what to send when. However, the ratio between the points to get and the LOC
to write is quite high.
Important: When implementing the functions, recall the TinyOS programming hint about the
forwarding of pointers!
One last hint: the interface IpPacket is wired by purpose.

For getting an overview of the network stack you can use make bigAVR6 1280 docs or even
make bigAVR6 1280 appdoc.

3.13 RandomAdcC (Read )

Similar to Section 3.5, this module implements a standard-interface provided by TinyOS. Contrary
to Section 3.5, however, this module shall perform high-gain ADC-conversions in differential mode on
disconnected pin (PK0/1). I.e., you should use the differential mode between ADC9 and ADC8 with a
gain of 200. These settings will lead to a high level of noise in the result, which allows to use the LSB
of the conversion result as an entropy source. Of course you also have to disable any pull-up on these
pins. See “tos/chips ecs/atm1280/adc/Atm1280Adc.h” for a list of possible configuration values for the
ADC. For further information, we refer you to Section 3.14 and [13, sec. 4].

3.14 RandomC (Random, ParameterInit)

To provide some randomness to the game, you have to implement a pseudo random number generator
(PRNG) based on a linear feed-back shift register (LFSR). Due to the fact that LFSR-based PRNGs
produce a fixed, periodic, stream of pseudo random numbers, you have to constantly reseed the register
with noise from the ADC conversion, as described in Section 3.13.
This module should provide an interface ParameterInit<uint32 t>, which is used by the main module
to set the period of the timer, which reseeds the LFSR. I.e., you should start a new conversion of the
RandomAdc whenever the timer fires. When the ADC provides a new value use the LSB of this value
to reseed the LFSR.
Details on the implementation of the PRNG can be found in [13, sec. 4]. As noted there, we recom-
mend you to implement the PRNG first in the provided C-Framework, and then port the tested PRNG
to TinyOS.

15
 Client Command Server Response
ping pong
start game ok: gameid id / err
set name id name ok/err
update score id score ok/err
end game id ok/err
get highscore 1: ... 2: ... 3: ... / end highscore

Table 6: List of the available commands for the communication with the scoreboard. Error responses
are separated from good responses by a “/”. Fields typeset in italic are variables.

Attention
It is not required to write the PRNG in assembler!

3.15 ScoreC (Score, Init)

This module is responsible for the communication with the scoreboard program via UDP.
The used communication protocol is defined in Table 6. It consists of a command to check basic
connectivity (ping), a command to acquire the current highscore (get highscore), and commands to
provide the scoreboard with information about the currently active game. The protocol has the following
format: command parameter1 parameter2.
Note that the acquisition of the current highscore table, will result in multiple messages being sent
by the server. Every entry is sent on its own, with the rank being at the start of the message, followed
by name and score which are divided by a ’−’. The last entry of the highscore will be followed by end
highscore, i.e., if there is currently no entry in the highscore a end highscore will be send immediately.

The score points in this game is the remaining fuel mass.

4 Theory Tasks
In the theory task we want you to develop argumentation skills that allow you to reason about the
problem you have to solve, and the solution you are designing. Clear presentation of ideas is crucial for
communication with team members, bosses, customers, etc. This time we want you to prove your answers
mathematically (e.g., by contradiction or induction). Points are solely awarded for proper mathematical
argumentation.
A fleet of n landers is orbiting moon at the equator. The landers constitute a logical ring that serves
as a communication network, and each participant may communicate exclusively by sending packets to
its right neighbor and receiving from its left neighbor. Each lander has a unique identifier, nodeID.
Moreover, it can check its remaining fuel.
The fleet should autonomously decide who lands first, depending on the remaining fuel. For that, we
assume that the lander with the most fuel serves as a controller.
The algorithm proceeds by sending packets that are lists of messages. We have two kinds of messages:
• (nodeID,fuel), where nodeID is the ID of a lander, and fuel represents the remaining fuel of a
lander.

• (nodeID,LAND), where LAND is a special symbol (indicating that the node with identifier nodeID
should land next).
The controller sends a packet containing a list (of length 1), that contains the message (nodeID,fuel),
to its right neighbor. Upon receiving a packet, a non-controller lander checks its local fuel, appends the
message (nodeID,fuel) to the received packet, and forwards it to its right neighbor. If the controller
node receives a packet, it checks for the lowest fuel and sends the packet (nodeID,LAND) with the

16
corresponding nodeID to its right neighbor (this packet contains one message). If a non-controller lander
receives (nodeID,LAND) from its left neighbor, it forwards it to its right neighbor. If, in addition, nodeID
matches its own nodeID, it lands. We say the algorithm is terminated when (nodeID,LAND) reaches the
controller.

Tasks
1. [2 Points] One landing: How many messages are sent globally (by all processes) until the algorithm
terminates? Prove by induction! (Note: if a packet contains ` messages, by appending a message,
one obtains a packet that contains ` + 1 messages. We are interested in the number of messages
sent).
2. [1 Points] Improvement: Give a distributed algorithm with better asymptotic message complexity!
As in the original algorithm, one of the landers with the least fuel should land. Provide instructions
(what packets to send, etc.) for the controller and the other landers. As in the original, the code
for the controller and the lander may be different. Prove that your algorithm is better!

3. [2 Points] Landing Fleet: Starting with a fleet of n landers, the above process is repeated n times.
How many messages are sent globally (by all processes) until the n iterations terminate? Prove for
the original algorithm and for your solution!

5 Demonstration and Protocol

If you want points for your application, you have to submit a *.tar.gz archive to myTI until 25.06.2017,
23:59. The name of the top-level folder of the archive must contain your matriculation number. Inside
the top-level folder place the Application folder from the template, and also include the Protocol folder
with the Listing.pdf. We enhanced the TinyOS build system with a target called code which generates
an appropriate archive. Please consult the README as to where you have to change a few variables,
e.g., set your name.
You are also obliged to participate in a delivery talk. The delivery talks will be held between the
26.06.2017 and the 29.06.2017. You must register in myTI for a 25 min slot. Please do so early, there are
enough slots for everybody (and we will open additional ones if necessary) but we cannot accommodate
everybody on the same day!
During the delivery talk, the tutor will download your application from myTI, check it and will walk
through your solution with you. Be prepared that the tutor asks you questions about your implementa-
tion. Only submissions that were approved by the tutor are counted. We also require you to print out
the first page of your Protocol (the version from the template is sufficient), sign it at the two marked
spots, and give it to the tutor at the talk.
You also have to write a protocol in LATEX, explaining your implementation and the decisions you
made during implementation. It should also contain a break-down of your working hours needed for the
application and list for which tasks you spent how much time (e.g., reading manuals, implementation,
debugging, writing the protocol, . . . ). The protocol, including the solutions for the theory tasks if
applicable, has to be submitted as a *.tar.gz archive to myTI until 02.07.2017, 23:59. The name of the
top-level folder of the archive should contain your matriculation number. Inside the top-level folder place
the Protocol folder from the template. Additionally to the LATEX files in the Protocol folder, include
the Protocol.pdf in the Protocol folder! The enhanced TinyOS Makefile provides a target protocol to
generate an appropriate archive.

5.1 Checklist
• Write Application
• Check that the listings.tex in the Protocol folder includes all source files
• Generate a code archive via the provided Makefile target code

• Upload archive to myTI

17
 • Download submission from myTI and
1. verify that the submission compiles in the lab and
2. works on the target as intended.

• Write the protocol. Prepare for the second exam.

• Generate a protocol archive via the provided Makefile target protocol
• Upload archive to myTI
• Download submission from myTI and check that all required files are included.

6 Grading
Please note that the points below are upper bounds that are possible to reach. However, there is always
the possibility of point deduction.
Therefore, if you aim for 20 points you should not gamble on dropping all theory tasks. Also remember
the “Collaboration Policy” at the course web page which enacts 15 points deduction for cheating for
everyone involved. Discussion among students is encouraged, but this is no group task. All programming
and theory tasks have to be done on your own!

Points Sub Part

20 Application
4 Lunar Lander
4 Physics
2 Gamepad
2 ADC
2 PS/2
2 Scoreboard
2 Ping + ICMP Port unreachable
2 clean TinyOS programming
5 Theory Tasks (every task is evaluated separately).

References
[1] MikroElektronika, Serial Ethernet Additional Board Manual. [Online]. Available: http://ti.tuwien.
ac.at/ecs/teaching/courses/mclu/manuals/extension-boards/serial ethernet manual v100.pdf/view
[2] Microchip, ENC28J60 Stand-Alone Ethernet Controller with SPI Interface. [Online]. Available:
http://ti.tuwien.ac.at/ecs/teaching/courses/mclu/manuals/extension-boards/ENC28J60.pdf/view

[3] “SDCard Index Application 2.” [Online]. Available: https://ti.tuwien.ac.at/ecs/teaching/courses/

mclu/misc/task2-specific-stuff/songlist.txt
[4] MikroElektronika, SmartMP3 Additional Board Manual. [Online]. Available: http://ti.tuwien.ac.
at/ecs/teaching/courses/mclu/manuals/extension-boards/smartmp3 manual v101.pdf/view

[5] VLSI Solutions, VS1011e - MP3 Audio Decoder. [Online]. Available: http://ti.tuwien.ac.at/ecs/
teaching/courses/mclu/manuals/extension-boards/vs1011e-mp3-audio-decoder/view
[6] NXP, “AN10441: Level shifting techniques in I2C-bus design.” [Online]. Available: http:
//www.nxp.com/documents/application note/AN10441.pdf
[7] STMicroelectronics, LSM303DLHC. [Online]. Available: https://ti.tuwien.ac.at/ecs/teaching/
courses/mclu/manuals/chip-datasheets/en-dm00027543.pdf/view

18
 [8] W. F. Rogers, “Apollo Experience Report – Lunar Module Landing Gear Subsystem,” National
Aeronautics and Space Administration, Manned Spacecraft Center, Houston, Texas, Tech. Rep.
D-6850, 1972.
[9] Wikipedia, “Apollo lunar module — Wikipedia, the free encyclopedia,” 2017, [Online; accessed
12-May-2017]. [Online]. Available: https://en.wikipedia.org/w/index.php?title=Apollo Lunar
Module&oldid=775173836
[10] Atmel Corporation, “AVR313: Interfacing the PC AT Keyboard.” [Online]. Available:
http://www.atmel.com/Images/doc1235.pdf

[11] “libmp3 source.” [Online]. Available: https://ti.tuwien.ac.at/ecs/teaching/courses/mclu/misc/

task1-specific-stuff/copy of srcmp3-1.0.tar.gz/view
[12] A. Hagmann, “VS1011e - mp3 audio decoder programming howto.” [Online]. Available:
http://ti.tuwien.ac.at/ecs/teaching/courses/mclu/misc/task2-specific-stuff/mp3-howto/view
[13] P. Fimml, M. Perner, and B. Petschina, “HOWTO: A Simple Random Number Generator
for the ATmega1280 Microcontroller under C and TinyOS.” [Online]. Available: http:
//ti.tuwien.ac.at/ecs/teaching/courses/mclu/misc/task2-specific-stuff/rand-howto.pdf/view

19