Getting Started with Oblog¶
Integrating Oblog with a robot project is easy - this page will provide a brief guide on the steps required to do it.
Adding Oblog as a Dependency¶
The first step to using Oblog is to add it to your robot project as a dependency. Oblog is distributed using jitpack.
To add Oblog as a dependency, we only need to add a couple lines to your project’s build.gradle
. First, add the following:
repositories {
maven { url 'https://jitpack.io' }
}
Secondly, add the following to the dependencies
list:
implementation "com.github.Oblarg:Oblog:RELEASE_TAG"
where RELEASE_TAG
is the latest release version tag (e.g. 3.0.3
).
If you wish to automatically build with the latest version of Oblog, you can use master-SNAPSHOT
instead of a release tag - keep in mind, however, that this may break your code without warning when Oblog is updated.
Configuring the Logger¶
Now that Oblog has been added as a dependency, it’s time to start logging!
The first thing to do is to determine which project class will serve as your “root container.” This is the “base class” of your robot, and will constitute the primary tab of your dashboard. For a basic robot project, this will likely be Robot.java
. For a command-based project, it will likely be RobotContainer.java
. For the purposes of this guide, we’ll assume a simple project is being used, and so Robot.java
is the root container.
Now, we’ll add the following call to the robotInit
method of Robot.java
(note: you will need to import the Logger
class from the io.github.oblarg.oblog
package):
// The first argument is the root container
// The second argument is whether logging and config should be given separate tabs
Logger.configureLoggingAndConfig(this, false);
The configureLoggingAndConfig
call takes the aforementioned “root container” as a parameter (since we’ve chosen Robot.java
as our root container, we simply pass this
since this call is located in Robot.java
itself).
Finally, we add the following call to the robotPeriodic
method of Robot.java
:
Logger.updateEntries();
The logger is now configured, and we’re ready to do some basic logging.
Logging a Field¶
To log a field in the root container, simply annotate it with the @Log
annotation (imported from the io.github.oblarg.oblog.annotations
package):
@Log
int exampleField = 5;
Note that the root container is specified by the configureLoggingAndConfig
call. If you want to log items from classes other than the root container, you must make those classes implement the Loggable
interface. For more information, see Creating Loggable Classes.
The field will be automatically added logged on the dashboard, and will track the value of the field in code. It’s that easy!
Of course, this is only a very simple example. For a description of the full set of logging features supported by Oblog, see Oblog Log Annotations.
Configuring a Field¶
Oblog doesn’t only support logging - it also supports configuring the value of fields from the dashboard! To bind a value of a field to an interactive dashboard widget, simply annotate a setter function for the field with the @Config
annotation:
@Config
public void setExampleField(int value) {
exampleField = value;
}
Oblog will automatically call the setter with the new value any time its value is changed on the dashboard!
The @Config
annotation can also be used directly on fields that implement the WPILib Sendable
interface. For a full description of the config features supported by Oblog, see Oblog Config Annotations.
Creating Additional Tabs¶
As our robot program becomes more complex, it becomes less and less tenable to just log everything in the root container’s tab. Oblog’s solution to this problem is to automatically infer the tab structure of your dashboard from the structure of your robot code. To enable it to do this, we use the Loggable
interface. Any field of your root container that implements the Loggable
interface will automatically be given its own Shuffleboard tab.
For an in-depth description of the use of the Loggable
interface, see Creating Loggable Classes.