Robot Development w FlashLib

This wiki page is still a work in progress

Do you need to create an amazing robot but want to do so quickly? Do you need a framework for you robot software so you won't have to create everything from scrach? Do you need your robot to do complicated tasks but don't know how?

If any of these are true (or any other reason...) you have come to the right place! FlashLib is not just a simple library, it provides a framework and a huge array of features and tools for any robot or just software in general.

To help you get start, we will be reviewing what you can do with FlashLib and how to use it to create your robot software. We assume that you do know a thing or two when jumping into this place, such as: what are motors, robots, sensors, etc.

Before we start, FRC programmers should refer to the FlashLib in FRC page to learn about using FlashLib with FRC robots because here we will be mostly discussing FlashLib for non-FRC robots.

Examples for robot code can be found here: Examples->robot.

Robot Control

Before starting with our robot software, we need to learn how our robot software is going to be managed and controlled. That is because planning and writing a robot software works a lot differently than applications for personal computers.

Main Class

A robot software contains a main class, which is resposible for integrating all the robot code into a single manageable place. The class will contain the objects which control our electronics, or perform algorithms and methods which use those objects.

Robot Systems

A robot is usually divided into systems, each responsible for performing different actions, and together they perform tasks. A system can be the robot's drive train, which includes the motors which move the robot. Another example can be an arm which is controlled by one or more actuators. All in all, a system is can be whatever we decide, as long as it makes sense.

Because our robot is divided into systems, we would usually divide the software similarly. Although not a must, we recommend making each robot system a different class. Those classes will have properties which will include objects and variables for controlling the system, and methods which will allow us to control the system from our main robot class. Once ready, we would create one object for each system in our main class and control those systems from there.

Electronics

Controlling a robot is basically controlling electronic devices on the robot which are connected to the robot computer. Those devices include actuators like motors or servos, as well as sensors like gyroscopes and ultrasonics.

To interact with those device our software needs to able to read and write into IO ports on the robot computer. There are several ways to do so:

• Writing code which will interact with the IO ports. This can be a difficult task and requires knowledge in IO and maybe even low level development.
• Using an external library. Chances are there is a library out there which already handles the interaction with IO ports for your platform, so it might be a better idea to find one and use it.
• FlashLib HAL. FlashLib provides and Hardware Abstraction Layer for IO on multiple platforms. The HAL not only takes care of IO interaction, but also manages port usage making everything safer. Unfortunately, FlashLib can not provide HAL implementations for every platform in existance, so it is also possible to provide a custom implementation.

Having a way to use IO ports is not the entire story, because we also need to know how to control each device with those ports. FlashLib provides several classes for device control, but manual creation might be necessary in some cases. To allow usage of those classes with any IO port interaction code, FlashLib uses interfaces for each port type. So when using a custom IO interction which is not included in FlashLib, simply implement those interfaces to use built-in control classes.

Operation Modes

FlashLib builds it robot framework on the bases of operation modes: a robot has several operation modes, in each mode the robot is controlled and performs different operations. A robot must have atleast 1 mode:

• disabled: This mode is a safety mode where the robot should remain idle and do nothing. This mode is a must.

Other than disabled mode, users can decide which modes the robot has. If the robot only has one operation type, the it would have a disabled mode and an operation mode.

An example for user defined operation modes can be:

• Manual: user manually controls the robot using controllers and joysticks, etc.
• Automatic: the robot executes pre-programmed instruction for performing and action, without user interaction.

Each mode is defined by an integer which is used to identify the mode. Disabled mode is identified as 0, user-defined modes can choose their own mode value. No 2 modes can should use the same value.

Mode Selectors

To select which operation mode is currently used, FlashLib uses the ModeSelector interface. This interface has a single method: getMode() which returns the current mode value. A robot can have only one ModeSelector.

There are several build-in mode selector types:

• Manual: the robot software manually selects which operation mode is used
• Flashboard: a control on the flashboard where users can choose the operation mode from the mode selector window.

Robot Control Loop

Unlike desktop programs or applications, robot software is built iteratively, meaning that our robot is managed by a loop. FlashLib provides robots with a loop which runs while the robot is operational, and from this loop user code is called. The loop takes care of different operation modes and allows our robot to operate without a stop.

Human Interface Devices

FlashLib provides a package for working with controllers and joysticks, allowing users to manual control the robot. However the problem is that there are many ways data from those controllers could be sent to our robot software. So to allow flexibility, FlashLib uses the HIDInterface interface which connects between the hid package and the actual controllers.

There are several built-in implementations:

• Empty: basically acts like no controller is actually connected.
• Flashboard: a controller which sends data about controllers connected to the Flashboard.

Robot Bases

Robot bases are classes which our main robot class should extend. Those classes contain the main method and are responsible for initialization and shutdown of the robot. FlashLib provides several robot bases.

RobotBase

RobotBase is the most basic base for robots. All other robots bases should extend this base. Here initialization and shutdown of the robot is handled. This class contains the robot's main method which should be called when starting the robot software. When the robot is started, the user implementation of this class is initialized, robot and FlashLib systems are initialized and user robot code is then started by calling robotMain(). When the JVM enters shutdown, this class uses a shutdown hook to perform ordered robot shutdown and will allow custom user shutdown by calling robotShutdown().

RobotBase has initialization parameters. To allow user customization, it is possible to override configInit(RobotInitializer) and customize initialization parameters. This method receives a RobotIntializer object which holds different variables, each affects initialization. This method has a default implementation that does nothing, so implement it only when custom initialization is wanted.

Initialization parameters include:

• The robot mode selector
• The robot HID interface
• etc...

Using RobotBase is not recommended because it is very basic and doesn't provide a robot control loop. Instead, extend one of the following bases, each an extension of `RobotBase:

SimpleRobot

A simple robot base, provides a control loop which calls a method when entering an operation mode.

The control loop tracks operation mode data and calls user methods accordingly. When in disabled mode, disabled() is called and allows user operations in disabled mode. When in any other mode, onMode(int) is called and the current mode value is passed, allowing user operations for that mode. Those methods are called only once when in the operation mode. So if they finish execution before the mode is finished, not further user code will be executed for that mode. If mode was changed and user code did not finished and the methods did not return, this will disrupt robot operations.

This class provides extended custom initialization. When the robot is initializing, preInit(SimpleRobotInitializer) is called for custom initialization. The passed object, SimpleRobotInitializer is an extension of RobotInitializer which adds additional initialization options.

Before the control loop starts, robotInit() is called. In here initialization of robot systems should be done. When the robot enters shutdown mode robotFree() is called to allow user shutdown operations.

IterativeRobot

An extended robot base, provides a complex control loop with easier control over operations.

The control loop divides each operation mode into two types:

• init: initialization of the operation mode
• periodic: execution of the operation mode init is called every time the robot enters a new mode. periodic is called every ~10ms while the robot is in the operation mode.

When the robot enters disabled mode, disabledInit() is called at the beginning and them every ~10ms or so disabledPeriodic() is called. When in any other mode modeInit(int) is called and the mode value is passed and then every ~10ms or so modePeriodic(int) is called and the mode value is passed.

This class provides extended custom initialization. When the robot is initializing, preInit(IterativeRobotInitializer) is called for custom initialization. The passed object, IterativeRobotInitializer is an extension of RobotInitializer which adds additional initialization options.

Before the control loop starts, robotInit() is called. In here initialization of robot systems should be done. When the robot enters shutdown mode robotFree() is called to allow user shutdown operations.

While the control loop is running, FlashLib's scheduling system is active allowing usage of it. When in disabled the Scheduler runs only Runnable objects and when in other modes both Runnable and Action objects are executed. When the robot switches operation modes, all Action objects are interrupted and stop running.

In addition, the control loop uses the motor safety feature of FlashLib to insure safe motor operations.

Getting Started

Prepering the IDE

Before we can start creating our software, we need to add FlashLib to the development environment we are using. Start by downloading the latest FlashLib release binaries. You will find 3 files of interest:

• flashlib.jar: The flashlib library. This JAR archive is the necessary file for using the library.
• flashlib-sources.jar: The sources archive. Contains FlashLib source files and not necessary for using FlashLib, just recommanded.
• flashlib-javadoc.jar: The Javadoc archive. Contains FlashLib Javadoc files and not necessary for using FlashLib, just recommanded.

We recommend creating a specific folder where FlashLib files will be placed, just for organization.

We now need to create a User Library in our IDE for FlashLib. This will allow us to easily use FlashLib in multiple projects. Depending on your IDE, this step will differ.

Eclipse

• Go to Window -> Preferences.
• Expend Java -> Build Path -> User Libraries.
• Click New.
• Name it FlashLib and click OK.
• Select the library in the window with the name you just choose and click Add External JARs.
• Navigate to the FlashLib JAR file flashlib.jar, select it and press Open.
• Expend the library and then expend the JAR you just added.
• Select Source attachment and click Edit.
• Choose External Location and click External File.
• Navigate to the sources JAR flashlib-sources.jar, select it and press Open.
• Click OK
• Select Javadoc location and click Edit.
• Choose Javadoc in archive, External File and click Browse for Archive path.
• Navigate to the Javadoc JAR flashlib-javadoc.jar, select it and press Open.
• Click Validate, a dialog will open and it should say Location is likely valid.. If that is not the case, repeat the javadoc steps and make sure you have selected the correct file. If everything is ok, close the dialog.
• Click OK.
• The library is now ready, click OK on the prefernces window.

Intellij IDEA

NetBeans

Creating a Project

Now we can create a project for our robot. We can use a simple Java project, all we need is to import our FlashLib user library and create a main robot file.

Eclipse

• Go to File -> New Java Project.
• Select a name for the project and location (if default location is not wanted).
• Click Next.
• Go to Libraries tab.
• Click Add Library, select User Library and click Next.
• Select the flashlib user library and any other wanted user library and click Finish.
• Click Finish.

The project is now ready in your workspace.

Intellij IDEA

NetBeans

Creating the Main Robot Class

The project is ready for use, so now we need to create the main robot class. This class will be the center of our robot, here we will integrate all the robot systems and run everything. Create a package for the main class file, the name does not affect the robot, so choose an appropriate name. Then create a class file in the package (not with the main method), we recommend calling it Robot.

Eclipse

• Select the created project, expend it and right click on src folder.
• Select New -> Class.
• Enter a package name where the main class will be located under Package.
• Enter a name for the main class under Name, we recommend Robot.
• Click Finish.

Now the main class is ready for use.

Intellij IDEA

NetBeans

Choosing a Robot Base

With the main robot class ready, all that we need to do is choose a base for our class which the main class will extend. A robot base contains the main method and is responsible for initialization of background operations and the robot operation loop. After choosing the robot base, extend the class with you main robot class and implement all necessary methods. Then we can start working on the robot software.