Startup Framework

The startup framework is software which we provide to allow us to start two robots simultaneously at the beginning of each match, and to ensure that they stop after 60 seconds.  The framework implements the procedure required by the rules, and you are not allowed to modify its functions in any way.  There are specific areas where you can add your own functions to implement your strategy for the competition.

Starting Procedure

This is an outline of the procedure.  The start-up procedure is defined in full in rules 14 to 24.  

Before the start of a match, you have 60 seconds to set up your robot on the competition table.  During this time, the beacons will be switched on.  You may use some of this time to calibrate your robot or to select a strategy, but you may not make any mechanical or structural alterations.  This is the pre-start phase - see the pre-start web page for ideas on what to do here.

Before the end of the set-up time, you must position your robot inside the appropriate starting area on the table.  It must be able to receive a signal from one of the beacons, as this signal will be used to start the match.  

The software will give audible and visible indications of the beacon signal being received.  You will be asked to confirm that your robot is receiving a beacon signal and ready to start.

When both robots are ready, we will switch off the beacons.  You will then be asked to arm your robot by pressing the START button on the Handyboard.  You must not arm your robot while the beacons are switched on.  At this stage, you must step away from the table and leave your robot to do its best without you.

When the beacons are switched on again, both robots start a 5-second countdown to the start of the match.  Each robot flashes a yellow LED and plays a tune for 5 seconds, so that we can confirm that both robots are about to start.  If there is any problem, we will abort the countdown.

At the end of the countdown, the startup framework will start your competition program.  Your program can do whatever you want it to do, to implement your strategy for the competition.

Our software stays running in the background, watching the time.  When 60 seconds have elapsed, the framework will stop your program.  It will also stop all motors and disable the servo actuator.  The match will end when everything comes to rest soon afterwards.

The same procedure will be used to start your robot in the ranking round, so you must use the framework software for the ranking round as well as for the competition.

Status Indicator

The startup software prints messages on the display to show what it is doing, but these cannot be read at a distance.  It also makes various sounds, but these can be hard to hear in a noisy auditorium.  To make it more obvious what is going on, you must connect a yellow LED for use as a status indicator.

Other Requirements

To make the start of RoboRugby matches run smoothly, we need easy access to the important controls on your Handyboard.  This means the ON-OFF switch, the START button and the STOP button.  You must design your robot so that these controls are accessible!

You will also find it convenient to allow easy access to the charging socket - you will want to charge your robot between matches. 

In its starting position, your robot must be able to receive a signal from one of the beacons.  This may put some constraints on the design and/or starting orientation of your robot.

It does not matter which beacon receiver you use for the start, but your robot must not receive signals from both beacons, as the beacon receiver can only handle one signal at a time.  This will require some shielding of the beacon receiver.  If you are using the same beacon receiver for navigation during the match, it will probably be shielded already.  If not, you will have to add another shield for the startup beacon receiver - if it is not for navigation, it can be a fairly simple shield.

How to Use the Software

The startup framework is provided as two files:  startup.ic  and  framework08.ic.  If you are using a desktop PC, these should be on it already.  If you have a laptop PC, you will have to download them -  you must save framework08.ic  in the same folder as your other programs, or else in the lib\handyboard  folder under Interactive C.

startup.ic  is the main file, which calls all the functions needed to implement the startup procedure.  You must edit this file and add your own functions to implement your strategy.  Then save it under a different name, which includes your team number.  This will help us to identify your program when we collect them all at impounding.  For example, team 3 could save their programs for the competition and the ranking round as  T03contest.ic  and  T03ranking.ic.

All the critical functions used in the startup framework are stored in the second file, framework08.ic.  You are not allowed to edit this file - in fact, you can ignore it completely unless you want to see how it works.

Combining with your program

The first lines in startup.ic  include other files and define constants and global variables:  

// - includes - you can add more #use commands here
#use framework08.ic
#use beacons.icb

// - defines - you can define more constants here using #define
// START_BCN_RX is beacon receiver for startup: 1 internal, 2 external
#define START_BCN_RX 2

// - globals - you can define global variables here
// global variable startbeacon is already defined, and will be 
// given a value during the startup sequence

You may need to add extra lines here to include other files or to define your own constants and global variables.  You may also need to edit the definition of START_BCN_RX - this tells the startup code which beacon receiver you want to use at the start.  You can use a different beacon receiver during the match if you wish.

The  main()  function has only a few lines, but it is critical to the startup and shutdown procedures - you may not edit this function.  You must rename your existing  main()  function as  rrmain()  - there is an empty function of this name already in  startup.ic .

If you wish to run any of your software during the pre-start phase, you must put this code in the  rrprestart()  function.  Again, there is an empty function of this name already in  startup.ic .

A simple example is available.

Restrictions on your program

To make the time-keeping work, it is important that the system time keeps advancing as your program runs.  This means that you must not use the  reset_system_time()  function in your program.  The startup framework will reset the system time at the start of a match, so your program can use the  seconds()  function to find out how much time has elapsed.

The usual  checkbeacon( ) function is included in framework08.ic, and is available for you to use.  We strongly recommend that you use this function to handle the beacons.  If you have your own function called  checkbeacon( ), you must delete it or rename it to avoid a conflict.

The startup framework defines a global variable called startbeacon, and sets it to 5 or 12, to indicate which beacon signal it received during startup.  To avoid a conflict, your program must not define a variable called startbeacon.  See below for details of how to use the beacon information.

The   rrprestart( )  function runs before the startup procedure.  It is not run as a separate process, so it must end within the 60 second time limit.  Typically, it will end when you press one of the buttons on the Handyboard, or when you press a switch on your robot.  You should not use any infinite loop in this function!  See examples on the pre-start web page.

So that the startup framework can stop all parts of your program after 60 seconds, it must know the process ID numbers of any extra processes which you use.  This means that you must use the  rrstart( )  function every time you want to start a process.  For example:

   rrstart(start_process(my-process()));

or in a more complicated case:

   pid = rrstart(start_process(my-process(2), 10));

In the second example, the process ID number is captured in the variable pid, so that you can kill the process yourself if you need to.  The process is passed an argument of 2.  The process is also given more time - 10ms instead of the default 5ms time slice.  This will make it run faster, at the expense of every other process.

Beacon information for your program

The startup procedure uses the beacon signals to start the two robots at the same time.  The framework also sets a global variable called startbeacon to 5 or 12, to indicate which beacon signal it received during startup.  This is available to all the functions in your program.

The meaning of startbeacon could be either your "home" beacon or your "goal" beacon - which one it represents depends on which beacon receiver you enabled for the starting procedure, and which way that beacon receiver was pointing at the start.  If you need to calculate the value of the opposite beacon, just use 

   otherbeacon = 17 - startbeacon;

The startup framework enables whichever beacon receiver you specify, but it disables it again before the start of the match.  This means that your program must enable one of the beacon receivers if you wish to use the beacons.  The syntax is 

   beacon_init(1);      // enable internal beacon receiver

or

   beacon_init(2);      // enable external beacon receiver

How it Works

This section explains how the startup framework software does its job.  You may ignore it if you wish. 

The  main()  function is fairly short, because most of the work is done in other functions:

void main() //Do not alter this function
{
   rrprestart(); // runs YOUR pre-start function,
      // to do calibration, choose strategy, or whatever...

   while(rrstartup(START_BCN_RX)); // start-up sequence
      // it is run again if it is aborted

   rrstart(start_process(rrmain(), 20)); // starts your main
      // program as a process, with a 20ms time slice

   rrshutdown(); // shuts everything down after 60 seconds
} // end of main

The  rrprestart( )  function is something which you can write, to do whatever calibration or selection you want to do before the start.  An empty function is provided so that you can ignore this if you do not need it.  

The next line is the startup sequence.  The rrstartup( ) function implements the startup procedure described above.  This is detailed below.  This function normally returns a 0.  However, if the startup is aborted during the countdown, rrstartup( ) returns a 1, and the while  loop makes it run again.

The third line is where the match begins.  The  rrmain( )  function is something which you must write, to implement your strategy for the match.  Notice that it is run as a separate process here - the  rrstart( )  function records its process ID number, so that it can be killed later.  By default, each process runs for 5ms in turn.  Because your program is doing all the important work, it is run for 20ms every time, while the main process only gets 5ms.

The fourth line is the  rrshutdown( )  function, which runs in parallel with your program.  After 60 seconds, it will shut down your program by killing its process and any other processes which it may have started.  It will also shut down the motors and servo actuator, in case your program has left them running.

rrstartup()

This function helps to ensure that the two robots start at the same time.  It is in the  framework08.ic  file.

It enables the requested beacon receiver, then starts a loop, checking the beacon signal every second, and giving an indication to the user by printing on the display, beeping and flashing the yellow LED.  Whenever a beacon signal is received, the global variable startbeacon is set to 5 or 12, for use in the match.

This loop will only exit when the START button is pressed, provided that there is no beacon signal, but there has been a beacon signal.  Pressing the START button in these circumstances arms the robot, and produces a high-pitched sound.  When the button is released, the yellow LED comes on and "Armed..." is printed on the display to show that the robot is armed. 

When the beacons are switched on again, the 5-second countdown begins.  The robot plays a 5-note tune, with the LED on for the second and fourth notes.  After each note, the function checks the STOP button and the beacon signal - if the button is pressed or the beacon signal is missing, the countdown stops and the whole procedure begins again.

If all is well, the function turns off the beacon receiver, resets the system time and exits.  The  main()  function will then start your  rrmain()  function to begin the match.