The CCRE: A comprehensive award-winning robot code framework

[Cel Skeggs]

Developed by FRC Team 1540, the Flaming Chickens, the Common Chicken Runtime Engine (the CCRE) provides a powerful yet easy-to-use software framework for use by FRC teams during competition season and beyond. It has a number of major features:

1. Separation of concerns: separation of concerns is where all code for specific functionality is in exactly one place, and is regarded as good for maintainability. The CCRE helps foster this using its higher-level abstraction and composition techniques.
2. Emulation: the CCRE has a fully functional emulator built right in! This means that robot code can be tested before deployment - very useful during build season when the robot that the code’s written for doesn’t exist for a few weeks.
3. Networked operator interface: the CCRE features a match-ready frontend known as the Poultry Inspector. It’s designed to replace (when used on a touch screen) or augment the physical control panels used by many teams with customizable information displays and controls.
4. Code portability: code written with the CCRE can run on both cRIOs and roboRIOs, from the exact same project. This minimizes the time needed for teams to get up to speed on roboRIO software. (The CCRE runs in Eclipse, which is the standard development environment next year.)
5. Support: the CCRE is completely open-source, and the primary developer can be directly contacted. (See the GitHub page for the email address.)
6. Prebuilt modules: the CCRE includes more complex self-contained modules of code that are useful for most robots, such as the Logging Framework, the Networking Framework, the Autonomous Framework, etc. This means that you get lots of helpful functionality with minimal work on your part.

The source code and documentation for the Common Chicken Runtime Engine can be found on GitHub.

As part of the documentation, we have fifteen tutorials on different parts of the system, from installation and simple robot code, to advanced guides on Logging and Cluck-based Networking.

See an example of CCRE code here!

The CCRE has now existed for about a year and a half, and we have used it for all of our robots in that time, which includes preseason, prototype, competition, and non-competition robots. After using it for the season, we presented on it at our competitions and it won the Archimedes Innovation in Control Award at the 2014 World Championships.

Note: This is the second CCRE thread on these forums. After a year more of development, we’ve decided to create a new thread with up-to-date information on the CCRE, as we were unable to modify the original post on the previous thread.

[Joe Ross]

Originally Posted by Colby Skeggs

Code portability: code written with the CCRE can run on both cRIOs and roboRIOs, from the exact same project. This minimizes the time needed for teams to get up to speed on roboRIO software. (The CCRE runs in Eclipse, which is the standard development environment next year.)

How do you deal with the non-backwards compatible changes in WPILib?

[Cel Skeggs]

Originally Posted by Joe Ross

How do you deal with the non-backwards compatible changes in WPILib?

Simple: we don't expose WPILib. FRC robot projects written using the CCRE access hardware through the Igneous class. This lets us smooth over any changes in WPILib.

Since the user project isn't the first thing that runs, the CCRE_Igneous_cRIO or CCRE_Igneous_RoboRIO module can register their own versions of the interface, so on the cRIO the interface is designed to work with 2014 WPILibJ, and on the roboRIO, the interface is designed to work with 2015 WPILibJ. When the user uses the "Deploy" target, it uses the roboRIO build system to download it (assuming that they have the required plugins), and when the user uses the "Deploy2014" target, it uses a heavily-modified version of the cRIO build system to download it, no plugins required.

In terms of the non-backwards-compatible hardware changes, we provide Igneous.isRoboRIO(), which lets the user program figure out which one is being used. Since a robot with the roboRIO and a robot with the cRIO would have different port numbers either way, we require that the user program chooses the correct port numbers itself. New modules such as the PCM are handled via methods such as Igneous.usePCMCompressor(), which will throw a helpful exception if used in a cRIO environment.

We've used this to make last year's code downloadable to both targets, and when our code ran on a cRIO at Girls' Generation and Rookie Rumble (offseason events), it used the exact same code that I've been downloading to a roboRIO for testing.

[NotInControl]

Originally Posted by Colby Skeggs

Simple: we don't expose WPILib. FRC robot projects written using the CCRE access hardware through the Igneous class. This lets us smooth over any changes in WPILib.

Since the user project isn't the first thing that runs, the CCRE_Igneous_cRIO or CCRE_Igneous_RoboRIO module can register their own versions of the interface, so on the cRIO the interface is designed to work with 2014 WPILibJ, and on the roboRIO, the interface is designed to work with 2015 WPILibJ. When the user uses the "Deploy" target, it uses the roboRIO build system to download it (assuming that they have the required plugins), and when the user uses the "Deploy2014" target, it uses a heavily-modified version of the cRIO build system to download it, no plugins required.

In terms of the non-backwards-compatible hardware changes, we provide Igneous.isRoboRIO(), which lets the user program figure out which one is being used. Since a robot with the roboRIO and a robot with the cRIO would have different port numbers either way, we require that the user program chooses the correct port numbers itself. New modules such as the PCM are handled via methods such as Igneous.usePCMCompressor(), which will throw a helpful exception if used in a cRIO environment.

We've used this to make last year's code downloadable to both targets, and when our code ran on a cRIO at Girls' Generation and Rookie Rumble (offseason events), it used the exact same code that I've been downloading to a roboRIO for testing.

If I understand this correctly, backwards compatibility only applies to programs purely calling WPILib, because you wrapped it and any code dependent on the Java standard libraries will not have backward compatibility. Is that correct?

What happens when the users program tries to execute code written under Java 8, but then tries to exectute on the cRIO? For example, if the user makes a call to Java.io.socket networking classes, or uses automatic unboxing Double myVar = 5.

All are valid on the roboRio, but what happens when the user tries to run this code on a 2014 cRIO, does it have a compile error, run-time error, or work somehow?

Thanks for putting this together,
Kevin

[Cel Skeggs]

Originally Posted by NotInControl

If I understand this correctly, backwards compatibility only applies to programs purely calling WPILib, because you wrapped it and any code dependent on the Java standard libraries will not have backward compatibility. Is that correct?

That's correct. We provide a few things from the standard libraries that aren't on the cRIO, but not anything significant.

Originally Posted by NotInControl

What happens when the users program tries to execute code written under Java 8, but then tries to exectute on the cRIO? For example, if the user makes a call to Java.io.socket networking classes, or uses automatic unboxing Double myVar = 5.
All are valid on the roboRio, but what happens when the user tries to run this code on a 2014 cRIO, does it have a compile error, run-time error, or work somehow?

When targetting the cRIO, the code is compiled with Java 1.5, not Java 8 or Java 1.3. It then gets run through Retrotranslator, which converts it to Java 1.3 bytecode.
Using unboxing should work properly, as far as I can remember. This is a language feature, not a bytecode or library feature. (You can use all Java 1.5 language features safely on the cRIO when using the CCRE, as far as I know.)
Using java.net.Socket will cause a compile-time error when targeting the cRIO (but not when targeting the roboRIO). This isn't an issue, though, because you can just use ccre.net.Network.connect(addr, port), which wraps both Squawk and Java SE interfaces for you into one interface.

In general, things will either just work or have a compile-time error. There are few cases when something will fail at runtime.

Originally Posted by NotInControl

Thanks for putting this together,
Kevin

Of course! Since it's licensed under the LGPL, any team that wants to use it (or any subset, really, but if you're going to use part of it, you may as well use the rest) is free to do so.

[Cel Skeggs]

Weekly update on 2014-10-27

CCRE release 2.1.1 is available.

Important changes since v2.0.0:
Added PIDControl.
Added Single Joystick drive.
Improved ExpirationTimer.

The devel-2.x.x branch has been created and has a variety of bugfixes on it, which will be in ccre-v2.2.0. (These fixes include removal of some legacy components, so it can't count as only a bugfix release.)

[Cel Skeggs]

Semi-weekly update on 2014-11-05

CCRE release 2.2.0 is available!

Changelog:
* Removed legacy version of the Poultry Inspector. This should not affect you.
* Moved ApolloGemini2014 to be another sample in SampleIgneousRobot, as would make more sense.
* TuningContexts will remember their names so that publishing a save event doesn't need to have the name specified again.
* TuningContexts will default to the global CluckNode if no node is specified.
* Added `Igneous.NO_RAMPING` constant, equal to 0.0f, which may be used as the ramping argument to `make*Motor`.
* Multiple interface savefiles are now supported by the PoultryInspector.

Bugfixes:
* Emulator failed to close if main code couldn't be loaded.
* Inverse trigonometric functions were unavailable on cRIO.
* (Partial) The build process paused a long time while old files are deleted.
* Emulator launch built more than was required, slowing down emulator launching.
* Poultry Inspector required Java 7, instead of Java 6.

As a reminder, we currently have a very active Trello board on which we keep track of current development status. For example, we have nineteen different cards under the "Done (October 2014)" column.

[Cel Skeggs]

Semi-weekly update on 2014-11-21

CCRE release 2.3.0 is available! Lots of goodies here - a total of 48 commits to our Git repository since the last release!

Major Changelog:

* Added booleans to TuningContext, so that the tuning framework works with them as well as floats.
* Added file and line number readouts to logging messages.
* Automatically set motors to zero on disable, to prevent ramping jumps.
* Added arithmetic on channels to FloatMixing.
* Added listing of robot addresses in PoultryInspector, instead of a preset address.
* Added lots of alternative views for PoultryInspector controls.
* Added method by which .input and .output for the same channel get shown as the same channel in the PoultryInspector.

Minor Changelog:

* Removed launches from TemplateIgneousRobot, so that only real projects get them.
* Sped up cRIO library building.
* Miscellaneous visual improvements to the Poultry Inspector.
* Cleaned up the implementation of the Mixing* classes: https://github.com/flamingchickens1540/Common-Chicken-Runtime-Engine/issues/7
* Added `IJoystick.getXSource()`, `IJoystick.getYSource()`.
* Made the averageBits parameter optional in Igneous.makeAnalogInput.
* Added OutputStream support to PoultryInspector.
* Cluck can now publish EventStatuses without manually breaking out the channels.
* Let DriverImpls Single Joystick Drive (Arcade Drive) take Joystick handles directly.
* Added unofficial copy of the Squawk source code to the repo so that source shows up.
* Added copy of the WPILibJ source code to the repo so that source shows up.
* Added roboRIO debugging support.
* Streamlined instantiation of TuningContext objects.
* Marked `makeAnalogInput_ValueBased` as deprecated.
* Added dynamic time waiting method to InstinctModule.
* Added direct access function for `Utils.currentTimeSeconds`'s value.

Bugfixes:

* Fixed incorrect Java versioning on some CCRE projects.
* Fixed off-by-one error with axes in roboRIO glue.
* Fixed the out-of-limit bug with PoultryInspector float readouts.
* Added backport rules for some mathematical functions that were unavailable on the cRIO.
* Fixed the bug where dragging out BooleanOutputs in the PoultryInspector would set them to false immediately.
* Fixed default positioning of the Logging Component in the PoultryInspector.

We also now have standalone downloads of the PoultryInspector binaries available with each new release. See the current release on GitHub for the binary download. (Scroll down a bit.)

As always, if you have any issues, suggestions, questions, comments, etcetera, about the CCRE, please post them here!

[Cel Skeggs]

Hotfix update on 2014-11-23

CCRE release 2.3.1 is available! This fixes a few problems, most importantly a major serialization bug introduced and present only in CCRE release 2.3.0. You should not be affected by this bug unless you're using the saved-layouts feature of the PoultryInspector.

Bugfixes:

* Fixed issue with saving PoultryInspector views that contain control components.
* Added keepalives for Cluck.
* Fixed ISOMETRIC_BUTTON stretching issue on PoultryInspector.

We try our best to keep the CCRE bug-free, and it almost always is. Of course, please report any issues or difficulties you have with the CCRE or any components, to help us keep it as high-quality as possible.

We recommend keeping your copy of the CCRE as up-to-date as possible. See the short update guide on GitHub.

[Cel Skeggs]

We're getting ready for release 2.4.0, but it's probably not going to be ready before Kickoff. However, we need to release all code before Kickoff by R13, so here are the details on where you can get it:

Everything is on the GitHub repository. The latest changes are in the devel-2.x.x branch, which is also publicly available. There is also a pull request in process (#10), which is also publicly available.

If you want the sum total of everything we have "unreleased" (it's public but we haven't signed off on it as a stable CCRE release), those two places will have it. We also plan to get them together into ccre release 2.4.0 soon, so you can also wait for that.

If anyone thinks that this doesn't satisfy R13, please let me know and I'll try to fix things.

[Cel Skeggs]

Release 2.4.0 should be up either today or tomorrow. The main thing remaining is to test the latest version to make sure that nothing's been accidentally broken since the last release.

Once this release is out, you will definitely want to upgrade - it has a number of fixes and improvements that are essential to programming the roboRIO with the CCRE, such as the rewritten Emulator that also supports the roboRIO.

We're also going to be pretty much requiring Java 8 now, so make sure to grab it from Oracle's site.

Also, we can see that a number of people have downloaded the CCRE recently! If you have, consider posting your opinions/findings here. (Especially if you plan to use it.)

[Cel Skeggs]

CCRE update on 2015-01-06

CCRE release 2.4.0 is out! This is the major 2015 season release - it contains working versions of most of what you'll need to use the CCRE in the 2015 season.

Major Changelog:

* A new Emulator model: DeviceList. This doesn't use screen space as well, but is easier to understand and only shows what your code uses.
* The Emulator now supports the roboRIO.
* Java 8 is now required for development.
* A new MultiModule system for easily selecting and configuring autonomous modes.
* Added an example of good usage of the CCRE by rewriting last year's robot code.
* ExtendedMotors were added, which allow for CAN motor support.
* Barebones CAN motor support.

Minor Changelog:

* The PoultryInspector now allows the END key to be used in place of ENTER to avoid disabling the robot.
* Added a version of `CluckTCPServer.setupServer` that takes a port number.
* Added FMS-compatible ports to roboRIO and PoultryInspector defaults.
* Added USB preset to PoultryInspector.
* Added `BooleanMixing.whenBooleanChanges` and `FloatMixing.whenFloatChanges`.
* `createDispatch` no longer ignores the initial value.
* The Emulator now reports errors in the GUI.
* Improved helpfulness of the message when the roboRIO plugin is not found.
* A wide variety of internal code enhancements.
* Moved the virtual phidget display to be a PoultryInspector component instead of a window.
* Added buildscript for the PoultryInspector's package.
* Added screenshots to PoultryInspector documentation.

Bugfixes:

* One implementation of `FloatMixing.onUpdate` was private.
* ConnectionReceiverThread always said port 80 when connection failed regardless of port.
* createDispatch now includes the original value in the result.
* Mixing.select now updates even when the selector stays the same.
* Fixed occasional link unavailable errors without useful information.
* Miscellaneous behavior fixes in Mixing methods.
* Miscellaneous concurrency fixes.
* Several other miscellaneous fixes.
* Fixed some minor licensing issues where the wrong documentation was provided.

We plan to build an Eclipse plugin for the CCRE at some point soon, which should make the CCRE much easier to install.

As usual, please send us any comments, questions, complaints, suggestions, etc!

[BrianAtlanta]

Your framework looks really nice. I was reading your documentation on the logging portion of the framework. You mentioned that some logging frameworks wouldn't run on the limited FRC setup. I was wondering if the change to the Roborio increased performance so that some of the logging frameworks would now work? I was looking at having our team look at something like Log4J, but I'm concerned it won't work.

Brian Carlson
Programming Mentor

[Cel Skeggs]

Originally Posted by BrianAtlanta

Your framework looks really nice. I was reading your documentation on the logging portion of the framework. You mentioned that some logging frameworks wouldn't run on the limited FRC setup. I was wondering if the change to the Roborio increased performance so that some of the logging frameworks would now work? I was looking at having our team look at something like Log4J, but I'm concerned it won't work.

Brian Carlson
Programming Mentor

The issue isn't with performance so much as the version of Java. The cRIO with just Squawk runs Java 1.3, which is a very old version. Log4j, for example, requires Java 6. With the introduction of the roboRIO, you can now use a number of these frameworks without too much work. The CCRE's Logging framework still has some advantages - it can work on any platform, including the cRIO, and by default works well with the rest of the system - no setup required.

You can certainly use Log4j, but you'd have to do your own work to integrate it.

[fsilberberg]

Originally Posted by BrianAtlanta

Your framework looks really nice. I was reading your documentation on the logging portion of the framework. You mentioned that some logging frameworks wouldn't run on the limited FRC setup. I was wondering if the change to the Roborio increased performance so that some of the logging frameworks would now work? I was looking at having our team look at something like Log4J, but I'm concerned it won't work.

Brian Carlson
Programming Mentor

One thing to note with Log4J and some other libraries is that with the embedded profile we use to create the JRE, some of the necessary bean components don't get enabled to save space. You could create your own JRE and put it in /usr/local/frc/JRE with the necessary components enabled, but we don't support it with the installer.