Installation

Note

BunyipsFTC users (members of the MBHS Student Robotics Club), BunyipsLib is already installed into the BunyipsFTC repo. All you need to do is create a new Gradle configuration for your robot by following the steps here. Other repositories should follow the installation instructions.

BunyipsLib is distributed via a git submodule. This allows for direct source code modification by you, as BunyipsLib should work harmoniously with your codebase.

To get BunyipsLib in your codebase, you'll need experience with git, the Gradle build system, and the command line (used in this tutorial). The recommended FTC SDK version is specified with one of the badges at the top of the README. The specified version is the one that BunyipsLib is tested with and will have the most compatibility. Generally, this is the latest version of the SDK as offered by FTC.

Integrating BunyipsLib into your codebase

1. Getting the code
   From the top-level directory in your own FtcRobotController fork, run git submodule add https://github.com/Murray-Bridge-Bunyips/BunyipsLib, which should clone and create a new BunyipsLib folder with the source code.
   
   
2. Adding dependencies
   BunyipsLib depends on RoadRunner, FtcDashboard, Dairy Sloth, and Kotlin. These tools make development faster and are legal FTC tools.
   You will first need to install Kotlin v1.9.20, alongside Dokka which is used for generating documentation. To do this, go to your copy of the FtcRobotController project, and open the top-level build.gradle file. Copy in the lines that are modified in the snippet below between the buildscript braces. Append these properties to their appropriate area.

buildscript {
   ext.kotlin_version = '1.9.20'

   dependencies {
       classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
       classpath "org.jetbrains.dokka:dokka-gradle-plugin:$kotlin_version"
   }
}

Your top-level build.gradle should look something like this. Note that this will install Kotlin on a global scope, meaning you can use Kotlin in user code too with the above dependency setup.

Important

These installation instructions are for BunyipsLib v7.x.x. Older versions contain different dependencies which are noted below.

After you've done this, go to your build.dependencies.gradle file located in your top-level directory and paste the following dependencies in the dependencies {} block:

implementation "dev.frozenmilk.sinister:Sloth:0.2.1"
implementation "com.acmerobotics.roadrunner:core:1.0.1"
implementation "com.acmerobotics.slothboard:dashboard:0.2.1+0.4.16"
implementation("com.acmerobotics.roadrunner:ftc:0.1.21") {
    exclude group: "com.acmerobotics.dashboard"
}

Finally, add these to the top repositories {} block in the same file:

maven { url = 'https://maven.brott.dev/' }
maven { url = 'https://repo.dairy.foundation/releases' }

Your dependencies file should look something like this.

Note

For BunyipsLib <5.0.0 - ≥5.1.0 note that PhotonFTC is a dependency, so the annotation can be removed from BunyipsOpMode if you don't wish to use it. (Photon is now optionally defined at your user-level OpModes, due to severe bugs and since the project is now archived. The last stable version of Photon is version v3.0.1-ALPHA).

Note

For pre-BunyipsLib v7.0.0, the build.dependencies.gradle file uses different dependencies. You can find the correct dependencies here.

5. Telling Gradle BunyipsLib exists
   First, we need tell Gradle to build BunyipsLib as well. To do this, open settings.gradle in your top-level directory and append the following lines.

include ':BunyipsLib'

Finally, we need to tell Gradle that we want to integrate BunyipsLib with the TeamCode module. Open the build.gradle file associated with the TeamCode module, and append to the dependencies {} block:

implementation project(':BunyipsLib')

5. Gradle sync
   In Android Studio, run a Gradle Sync (Ctrl+Shift+O) to ensure your classpaths are updated with BunyipsLib and your dependencies are downloaded.
   
   
6. You're done!
   You now have access to BunyipsLib. Ensure to read how to update BunyipsLib and how to ensure your future cloners can get BunyipsLib in their local repositories.

Using the BunyipsLib submodule in a clone of your fork

For new cloners of your fork with BunyipsLib, you can simply run git clone --recurse-submodules <YOUR_REPO>.

For repositories that already exist, run git submodule update --init --recursive, to fetch the submodule that was placed in your .gitmodules top-level directory file.

Updating BunyipsLib

BunyipsLib is continually getting updates to ensure the latest features have been rigorously debugged and tested. To ensure that you aren't using code that I've accidentally implemented a 30-gigabyte memory leak into (it has happened before), you'll need to know how to update it.

Navigate to the directory of your BunyipsLib submodule, and run git pull on the master branch for the latest dev changes. This should bring any changes into your repository. If you wish to use a more stable version of BunyipsLib, you can switch to the SemVer tags that are available in the repository using git checkout <tag> and available in the Releases section. These versions are more stable and are less likely to have runtime errors or bugs, with changes fully documented.

Warning

Your main TeamCode package should be org.firstinspires.ftc.teamcode, in order to ensure compatibility with the class loader and additional SDK features such as the Java to Blocks (myBlocks) interfaces. Standard FtcRobotController forks do not need to worry about this.

Using Sloth Load (Fast SDK deployment)

BunyipsLib comes integrated with Dairy Sloth, a runtime for Dairy Sinister 2.0. Many features of Sinister are used internally by BunyipsLib, but Sloth allows dynamic loading of the SDK modules to assist in build times.

Many programmers know the struggle of waiting for Gradle to execute, and one of the primary benefits of Sloth is that this installation time is now cut down to around 2 seconds for a full deployment. Sloth also supports keeping changes across power cycles.

Important

For maximum reliability, a full standard build should be performed to eliminate any risk of unexpected bugs in the hot-reloading module. A general tip is to do this at the end of your debugging session with the robot, or before it goes into competition.

Using Sloth Load in BunyipsLib simply requires you to add the Load Plugin and Gradle configuration. For standard SDK projects, use the installation instructions here.

For projects such as the MBHS Student Robotics Club BunyipsFTC, you can follow this quick list, or follow the official instructions here:

1. Add this segment to your robot module's build.gradle

buildscript {
    repositories {
        mavenCentral()
        maven { url "https://repo.dairy.foundation/releases" }
    }
    dependencies { classpath "dev.frozenmilk:Load:0.2.1" }
}
apply plugin: "dev.frozenmilk.sinister.sloth.load"

2. Gradle sync and perform a standard build to your robot
3. Add a new build configuration in the top menu with the robot selector
4. Select Gradle, give it a name (such as Robot (Sloth Load), Robot being your module name such as Proto, Vance, Joker, etc.)
5. Set the run target to :Robot:deploySloth (use your module name instead of Robot)
6. Save this new configuration, note you can save this configuration as a project file in the top right for it to sync on GitHub for others (recommended)
7. Apply and select your standard build configuration (Android App/Robot, etc.)
8. Under Before launch at the bottom, click the plus and add a Run Gradle task
9. In the Gradle project type :Robot (use your module name) and select the first suggestion
10. Set the Tasks field to removeSlothRemote
11. Click OK and use the up arrow to move the Run Gradle task you just made above Gradle-aware Make
12. You're done. You can deploy via Sloth Load by running this Gradle task you just made, but ensure to perform a full build before using Sloth Load. If something goes wrong, try another full build install as some files may not have made their way to the robot.

Note

Sloth Load will hot-reload any changes made inside your robot module. It will not fast-reload any changes you make to BunyipsLib; a conventional install will be required. Changing BunyipsLib code and performing a fast-reload with dependencies on changed code will result in undefined/crashing behaviour.

Important

Sloth is very recent software. It may have unexpected crashes or undefined behaviour. Always run a full build when in doubt.

What's next?

Once you've installed BunyipsLib, start looking at the various paradigms related to using BunyipsLib, as well as how to configure your robot.