Introduction to laboratory facilities for module EE303: Mobile Robotics
Prof. Noel O’Connor
Acknowledgement
Thanks are due to Robert Clare for looking after the lab equipment for this module so well. Thanks are also due to Liam Meany for his continuing Linux support and his contribution to these notes.
1 Introduction
This document is intended to give an overview of the laboratory facilities associated with module EE303 Mobile Robotics. Some of these facilities may be well known to you (e.g. via other modules), whilst others will be completely new. It is imperative that you quickly become comfortable with the lab facilities in order to get working on the task in hand - actually building your robot - as soon as possible. This document is intended as a “quick start” guide in order to assist you getting up and running. However, this introduction is brief and should only be considered as a jumping off point ...
2 The Mobile Robotics Laboratory
For this module, you will spend the majority of your time in the Mobile Robotics Lab. In fact, the only conceivable time you should not be working in the lab is when you are doing some background reading/research e.g. in the library. The laboratory contains all elements required for the day-to-day work on your robot: • the official Mobot track;
• the small test track;
• boxes of lego pieces, gears, etc;
1 • soldering iron;
• sensors and their data sheets;
• the computer facilities required to:
– design the program which will control your robot; – download these program to the HandyBoard; – write the final report associated with the module.
The remainder of this document is divided in two sections. The first gives an overview of the computer facilities available. By necessity, this requires an introduction to the Linux operating system. The second section is devoted to Interactive C, the actual programming language used in order to control the HandyBoard and hence your robot.
3 Getting Started with Linux
3.1 Introduction The machines in the Mobile Robotics lab all run the Linux operating sys- tem. This is a high performance operating system available for a variety of hardware platforms including Intel based PCs ...and it’s free!. Standard dis- tributions include the full GNU compiler and many other development tools. Linux has long been a very popular choice as a platform for serious software development, and is becoming more so all the time. During the course of this module, you will learn about (and find your way around) a popular Linux distribution.
3.2 The basics Many of the basic concepts and functionalities of Linux will be familiar to you already ... although you may not know it! You will have been introduced to various elements in a “piece-meal” fashion. However, some of the terminology and commands used may be new to you. Some basic Linux concepts and terminology are outlined below:
• Shell prompt: A command line interface (CLI) interface between the user and the operating system. The shell interprets commands entered by the user and passes them on to the operating system. The shell prompt displays the command line.
2 • Command line: The place in the shell prompt where commands are typed.
• Command: An instruction given to the computer either by typing or using the mouse. Some commonly used commands in a shell are:
– pwd: “print working directory” - displays the user’s current loca- tion in the file system hierarchy – cd: “change directory” - makes another director the current loca- tion. When working with file systems, ‘‘.’’ is shorthand for the current directory, whilst “..” is shorthand for the parent directory in the file system hierarchy. – ls: “list files and directories” - displays a listing of files and direc- tories in the current working directory. A “long” listing indicating extra information (time/date of creation, size, owner, privileges, etc.) can be obtained using ls -l. – cp
• Graphical User Interface (GUI): A screen with icons, menus, and panels and toolbars on which the user can click in order to initiate functions.
3 3.3 Logging In For the purposes of this module, each group will be assigned their own PC. To log into your assigned PC, enter your regular login details (as for windows PC’s in the other laboratories).
3.4 The XFCE desktop environment The long bar across the bottom of the desktop is known as the panel. The panel displays application launchers and status indicators, such as the current time, minimized applications you are running, and more. The icons elsewhere on the desktop can be file folders or application launchers. To open a folder or launch an application, double-click on its icon. A window in which an application is running (e.g. a shell, Firefox, emacs, ...) can be minimized, or ”hidden”, by clicking on the left-most button in the upper-left corner. Buttons for minimized screens appear in the panel at the bottom of the screen. Windows can be maximised using the second button from the right in the top corner. If you lose track of the windows you have open you can middle-click (or hold down both mouse buttons simultaneously if your mouse only has two buttons) on the desktop and place your cursor over Windows. A list of open windows appears and you can select the one you want to bring to the fore. XFCE provides you with Multiple Desktops. This means that instead of crowding all your work onto one screen, you can use virtual desktops, which extend your workspace to multiple desktop areas. For example, you may have Firefox (or multiple versions thereof) open in one desktop, email (see below) in another, all your text editors in another, and the shell reserved for downloading pcode to your robot in another.
3.5 Xterms A Command Line Interface known as a Terminal Emulation Program or Xterm can be launched from the XFCE panel. To do this, simply click on the icon on the panel - a VDU with the XFCE panel. This launches a window within which a shell is run. Many different Xterms can be run at the same time facilitating using one for downloading pcode, one for telnet or ftp, one for launching your text editor, ... The most important thing to learn/remember before proceeding any fur- ther is that Linux is case sensitive!. This means that typing “cd Source” and “cd source” are two different commands. The first means change work- ing directory to one called “Source” whilst the other means change working
4 directory to a (different) directory called “source”. Typing “ls -l” will list all files/directories in your home directory. You should recognise the files/directories listed as a result of this command - they correspond to the contents of your School of Electronic Engineering user account. Your account is “transparent” across all the School’s computing resources (i.e. machines running Windows NT in the CAE or main labs, Unix-based servers and the Linux machines in the Mobile robotics lab). You can use an Xterm in order to download pcode to the HandyBoard and run Interactive C (IC) as outlined in Section4.2. The shell that we use supports filename and command completion. This means that you do not have to type an entire file name/command but can simply type the first few characters and then hit the TAB key and the shell will attempt to complete the file name/command for you:
$cd mob
$cd mobile robotics assuming a directory named mobile robotics exists in the current directory. If there is more than one file name/command with the same initial characters, the file name/command will not be completed, rather hitting TAB again will show a list of potential “matches”. This allows to you to type a couple more characters in order to uniquely identify the file name/command you want by hitting TAB again. Initially, this may seem like a strange concept and more trouble than it is worth, however, when you get used to this feature it becomes second nature and allows very rapid command line navigation.
3.6 Running Mozilla Firefox To run Firefox simply select this application from the menu or alternatively type:
$Mozilla firefox & at the prompt in the shell (where the ampersand means “run Mozilla Firefox as a background process”). You will need to enter the proxy settings in firefox. To do so:
• Start Firefox (as described above)
• Choose the “Tools” menu and click on “Options”.
5 • Click the “Advanced” tab at the top of the “Options” dialog box to display the advanced settings for your Firefox browser.
• Select the “Network” tab near the top of the “Option” dialog box.
• Click the “Settings” button under the “Connection” category in the “Options” dialog box to bring up the “Connection Settings” dialog box.
• Select the “Manual proxy configuration” radio button. The text boxes below the selection will now be enabled so you can enter the proxy settings for your Firefox browser.
• The proxy address is proxy.eeng.dcu.ie and the port number is 80.
3.7 Text Editors 3.7.1 Interactive C GUI Text Editor Please note that for ease of use you have been provide with an Interactive C Graphical User Interface (GUI) to help you interact with the HandyBoard. This GUI contains a text editor which you can use for editing your source code. Details on how to start up and use the GUI are given in section 4.2.1. You can then download and run the source code by clicking on the appropriate buttons at the top of the GUI. Using this GUI is a the easiest and most straightforward way of programming your HandyBoard but you may prefer (or just be interested to know how) to use separate text editors and Xterms to program the HandyBoard - this is explained below.
3.7.2 External Text Editors Alternatively you can use a separate text editor. You have a number of options available to you, but the most popular are two applications called pico and emacs. pico runs within the current shell, whilst emacs runs in its own window once invoked. Either can be invoked for a particular file (creating the file if it doesn’t exist) by typing:
$pico filename.c $xemacs filename.c &
Personally, I recommend using emacs. Although it may take a little bit longer to get used to, it contains many (optional) powerful features (e.g. code high- lighting, kill-replace ring, etc.) which are particularly useful when writing C
6 code. The default appearance/behaviour of emacs is controlled by a resource file called .emacs, which should be resident in the user’s home directory. A detailed emacs tutorial is outside the scope of this document, however a few basic controls are outlined below. Multiple files can be opened and edited simultaneously with emacs. Each file is stored in a separate memory buffer. emacs itself is most efficiently controlled by a sequence of keystrokes. Some of the more commonly used keystrokes are listed below. In this list, the notation CTRL-x -> CTRL->s means “press the CTRL key and hold it down whilst hitting x, followed by s”. Filename completion is supported for any commands involving file names. • CTRL-x -> CTRL-f -> filename: open file named filename in a new buffer
• CTRL-x -> CTRL-s: save the file in the active buffer to disk • CTRL-s ->
• CTRL-x -> CTRL-b -> filename: switch to buffer containing filename • CTRL-x -> CTRL-k: kill current buffer (you will be prompted to save if the buffer has not been saved since the last modifications)
• CTRL-g: cancel current command (i.e. current sequence of keystrokes) ... very useful when learning emacs and getting used to these commands
• CTRL-x -> CTRL-c: exit emacs • CTRL-v: go forward one screen in the active buffer • ALT-v: go backward one screen in the active buffer • CTRL -> LEFT/RIGHT ARROW: go forward/backward one word in active buffer
• ALT-x -> TAB: list all available emacs commands • ALT-x -> he -> TAB: list all available emacs commands starting with the characters “he”
• ALT-x -> help: emacs help utility As you might guess from the above it takes a little time to master using emacs, however, the effort is worth it! When you become proficient in only a few commands, you will find that emacs is a very powerful editing tool!
7 3.8 Accessing Email You can access email in exactly the same way as you would from any of the School’s other computer labs - simply start Firefox and access the DCU mail system.
3.9 Logging out To log out from XFCE, go to Main Menu Button and select the “Log out” option. When the confirmation dialog appears, select the Logout option and click the “Yes” button. If you want to save the configuration of your panel, as well as any programs which are running, check the “Save current setup option”, as well.
3.10 Final note A complete guide to navigating the Linux operating system is outside the scope of this document. There are many powerful concepts that are hugely useful but are not explained here. This is intentional as in many cases the best way to become familiar with these concepts and tools is to start using them rather than reading about them. Having said that, there are many books available on this subject ranging from beginners’ guides to advanced system programming under Linux. In addition, there are many tutorials available on the web regarding getting started with Linux. Part of your initial work in this module is to perform this research so that you can quickly become comfortable within this new programming environment (it may be the only opportunity you’ll get in the entire 4 years of your degree programme). Familiarity with the Linux operating system is an extremely useful skill to have on your CV. Many potential employers are impressed by graduates who possess software skills that are transferable across different computing platforms (e.g. Windows, Linux, Unix, ...). Furthermore, very often software- based final year projects (worth 25% of the marks for your final year!) may require C/C++ programming under Linux/Unix. Although the main objective of this module is not to teach you about the Linux operating system, it is an ancillary objective that we have built into the module. Of course, as you know from previous labs, the Handy Board and Interactive C can be used under WindowsNT. In previous years, rather than taking the time to research, study and learn their way around Linux, some students have decided to simply use the machines in the CAE lab for this purpose. This is understandable, as dealing with a completely new operating system can be daunting. In my opinion, however, this is a mistake. For a
8 little effort up front you can add another string to your software/computing bow. Also, from a practical point of view, it will quickly become tedious having to run back and forth from the CAE lab to adjust small parts of your code ... especially when the pressure is on in the final stages of the module.
4 Interactive C
4.1 Overview Interactive C (IC) is a C language consisting of a compiler with interactive command line compilation and debugging and a run-time machine language module. It implements a subset of C including control structures (i.e. for, while, if-else), local and global variables, arrays, pointers, structures, 16- bit and 32-bit integers, and 32-bit floating point numbers. IC works by compiling into psudeo-code (pcode) for a custom stack machine - in this case the microprocessor on the HandyBoard which will control your robot. This psuedo-code is then interpreted by the run-time machine language module. This approach offers the following advantages:
• ease of design and portability - since IC psuedo code is machine inde- pendent, porting the code to another platform simply means re-writing the pcode interpreter (significantly easier than writing a compiler for a typical processor)
• small object code - stack machine code tends to be smaller than native code
• multi-tasking - because the psuedo-code is fully stack-based, a process’s state is solely determined by the stack pointer and program counter. Thus, it’s easy to task switch by simply loading a new stack pointer and program counter. This can be handled by the run-time module.
4.2 Downloading pcode and running Interactive C 4.2.1 Interacticve C GUI As mentioned above you can use the Interactive C Graphical User Interface to download, run, simulate and edit source code. To open the GUI open up the terminal and type icwin. A dialog box should appear prompting you to select the appropriate port. If you have connected the HandyBoard to COM1
9 then choose the first option. A new dialog box should appear, detecting your hardware and prompting you to download the appropriate firmware. Select the “Download” option. Make sure your HandyBoard is in download mode. To switch to download mode, hold down the Stop Button while switching on – the green and red LEDs should stay off. You can now use the GUI to interact with the HandyBoard and to edit your IC source code.
4.2.2 Xterm alternative to GUI Before you can use IC, you need to first download the run-time module onto the board. First, connect the board to the computer via a serial port (referred to as COM1) and switch the board to download mode. You should then see the run-time module being downloaded . Then type the following command at the shell prompt:
$dl pcode hb.s19 (-port /dev/cua0)
You should then see the run-time module being downloaded (the green LED should flicker). The run-time module is started by turning the board off and on again. To run IC simply type:
$ic (-port /dev/cua0)
You are now ready to go!
4.3 Interactive C Commands You will need to become familiar not only with the IC programming language but also with the command line interface for running IC interactively when testing your code. Some example commands are outlined below:
• load file - loads a named C file (multiple files can be loaded at once)
• unload file - unloads named file
• list filesfunctionsglobals - lists the names of all files/functions/globals currently loaded
• quit - quits interactive C
10 The complete set of commands can be found in the IC manual. The best way to get familiar with IC is to start experimenting with it. This will help you become familiar with commands such as those outlined above, but will also serve to dust the cobwebs off your C programming skills and quickly get you up to speed on developing source code in a Linux envi- ronment.
4.4 Example 1: A Simple example As an initial experiment with IC, I would suggest to proceed as follows:
• open two xterms (shells)
• in one shell go through the process of downloading the pcode mod- ule to the Handy Board and subsequently running IC. This xterm will be reserved exclusive for running IC commands, invoking functions, etc.
• in the other shell, launch a text editor with a new file called test.c. This text editor will be used to edit/create your source code. Remember to save your work every time you make a change (of course every time you make a change you also need to re-download your code).
Your first attempt at IC source should be quite simple. For example, you might create a single function in test.c such as:
int hello(void) { printf("Hello!"); sleep(15.0); beep(); printf("How are you?");
return(1); }
This function simply outputs a simple text message on the Handy Board display, goes to sleep for 15 seconds, causes the Handy Board to emit a beep and then prints another mesage on the display. Save the file and switch to the IC xterm. In the IC xterm you can then type:
11 $load test.c at the IC prompt. You should then see your code downloading to the Handy- Board. To check that your code has been downloaded you might type
$list functions at the IC prompt which returns a list of all currently loaded functions. The last one in the list should be hello(). To run your function simply type:
$hello() at the IC prompt and watch (and listen!) to make sure it runs correctly At this point you should read the IC manual (available through the local links section of the notes) and start to extend your simple example. In each case, develop your code in one shell and switch to the other in order to run/test it. To extend your code, you could:
• investigate adding variables/macros/pre-processor directives
• investigate the beeper functions: beep(), tone(), ...
• connect up a motor to the HandyBoard and investigate the motor func- tions: fd(), bk(), motor(), ...
• start to familiarise yourself with the sensor functions
Note: You will have to include the software you develop for your robot in the report submitted at the end of the module. There will be marks going for code which is well commented and clearly laid out, making proper use of indentation etc., so it’s a good a idea to get into the habit of doing this as early as possible.
4.5 Example 2: A More Advanced Example When designing and implementing the software which will control your robot, you will have to make use of multi-tasking. As such, in this section I provide an overview of IC multi-tasking and how to implement it. In order to illustrate multitasking I will refer to a sample IC line following program I found on the Internet. This program consists of two source files, globals.c and sample.c, which are now available at: http://www.eeng.dcu.ie/ ee303/ic- sample/
12 Note: Whilst the sample program is a simple line following algo- rithm, it is extremely rudimentary in nature. In fact, its actually incomplete and will not work at all! Its up to you to implement a proper line following algorithm (and the rest!) for your robot. Of course you can use this code as a template if you wish ...
4.5.1 IC Multi-tasking One of the most powerful features of IC is its multi-tasking capability. This means that processes can be created and destroyed dynamically during run- time. In fact, any C function can be spawned as a separate task and multiple tasks can be created that run the same code but have their own local vari- ables. Your robot will be controlled by a number of processes (implemented as C functions) which are running concurrently. For example, you will probably have a number of processes to examine the data produced by the various sensors you are using, whilst other processes will cause the robot to re-act to this data as it becomes available. Processes communicate with each other via global variables. Typically, one process will set a global variable to some value based on sensor input, whilst another process will be then be able to read this variable and specify the appropriate action. For example, the file globals.c declares variables for flags indicating that the right or left photodetector sensed the white tape (right detected and left detected) which are assigned a value based on sensor input. Similarly, a variable for motor control (mc) is also declared which can be set to an appropriate value based on the value of these variables at a given instant. Incidentally, a set of global variables for the various analog and digital ports are also be declared and initialised in globals.c (i.e. Right Detector and Left Detector). This allows these ports to be referenced with an alphanu- meric identifier (i.e. by name) in the source ...making the overall program more readable and easier to follow by others (particularly by those doling out the marks!). Typically, the body of a function implementing a process runs within an infinite while loop, since you want the process to run until you explicitly stop it (i.e. kill it). For example, the function Right D( ) in sample.c implements an infinite loop since (in this case at least) the robot should be continually trying to sense the white tape. Within the loop is the actual detection code. In this case it checks whether the value returned from the analog port cor- responding to the right detector is greater than some threshold, and if it is, the value of the global variable right detected is set to 1 (or TRUE). Simi-
13 larly the function arbitrator( ) loops forever, each time checking the value of the variable right detected and taking appropriate action (specifically, setting the motor control variable mc).
4.5.2 Process Scheduling Each time a process runs, it executes for a certain default number of millisec- onds (in this case five). After its “turn” ends, the next process is run. All processes are kept track of in a process table; each time through the table, each process runs once. The IC defer( ) function can be used to make a function swap out immediately. This is useful if it is known at a certain point in the code that the process will not have to do any more work until it is next scheduled. For example, the Right D( ) function’s job is done after it checks the sensor value against the (pre-determined) threshold and sets the global variable accordingly and thus can be immediately swapped out. The IC function hog processor( ), on the other hand, allocates an addi- tional 256 milliseconds of execution to the currently running process. Beware however, that if this function is called repeatedly (in a loop for example) only the process calling it will be executed. Only a full reset will get you out of this situation! As such, take extreme care using this function.
4.5.3 Creating and Killing Processes A process can be started using the IC start process( ) function, which takes one mandatory argument - the function call to be started as a process. This function returns a unique process identification (PID). It is extremely important to keep track of PIDs since they are used to subsequently kill processes using the IC kill process( ) function. For example, the main( ) function in sample.c starts up four processes, stores the PIDs in local variables, goes to sleep for 30 seconds and then kills all processes.
14