Whats an api

According to the official FTC Docs, an API is a documented interface for a software library or repository that allows programmers to learn what specific methods can do, what inputs they require, and what outputs they provide. Additionally, the FTC SDK API contains classes and interfaces that provide software access to hardware components, such as absolute orientation sensors. External libraries like Road Runner also publish their own API documentation, which can be found in their online API reference docs .

Was this right?

Sources16

FTC SDK API > com.qualcomm.hardware.adafruit > AdafruitBNO055IMU

FTC SDK API·BSD 3-Clause

Instances of AdafruitBNO055IMU provide API access to an Adafruit Absolute Orientation Sensor .

Open FTC SDK API

API Docs

This source does not publish a licence, so its text is not reproduced here. Open the source to read it.

Open Road Runner

API Docs

This source does not publish a licence, so its text is not reproduced here. Open the source to read it.

Open Road Runner

External Libraries in OnBot Java and Blocks > Overview

FTC Docs·BSD 3-Clause

It’s a simple process with three basic steps.

Step 1, find a library with features you want to use, and get its .jar or .aar file.

Step 2, upload that file in OnBot Java.

Step 3 has three variations, depending on your planned use of the library.

Step 3A assumes you want to use a library function, or method, in OnBot Java only. Namely you are not planning to make that method available for Blocks users.

Step 3B assumes that you do want to provide the library method to a Blocks user, by creating a special Block called a myBlock. MyBlocks are not new with 7.0, but now you can use library code in that myBlock. You can create your myBlock to have the exactly same inputs and outputs as the library method, or slightly different inputs and outputs.

Step 3C is a different scenario, where the library method is made available directly to the Blocks user, without creating a myBlock. This can be done, if the library is specially annotated by its author.

Open FTC Docs

External Libraries in OnBot Java and Blocks > Summary

FTC Docs·BSD 3-Clause

Blocks and OnBot Java programmers can benefit and learn from this new capability with external libraries.

You are encouraged to submit other examples and suggestions that worked for you.

=============

Questions, comments and corrections to westsiderobotics@verizon.net

Open FTC Docs

External Libraries in OnBot Java and Blocks > Advanced

FTC Docs·BSD 3-Clause

Here are some technical details that might apply to very advanced use of the External Libraries feature. These are not covered in this basic tutorial.

.aar files with assets are not supported
External libraries can include .so files for native code
External libraries can add new hardware devices with these

annotations:

com.qualcomm.robotcore.hardware.configuration.annotations.AnalogSensorType
com.qualcomm.robotcore.hardware.configuration.annotations.DeviceProperties
com.qualcomm.robotcore.hardware.configuration.annotations.DigitalIoDeviceType
com.qualcomm.robotcore.hardware.configuration.annotations.I2cDeviceType
com.qualcomm.robotcore.hardware.configuration.annotations.MotorType
com.qualcomm.robotcore.hardware.configuration.annotations.ServoType

External libraries can add new functionality to the Robot Controller

with these annotations:

org.firstinspires.ftc.ftccommon.external.OnCreate
org.firstinspires.ftc.ftccommon.external.OnCreateEventLoop
org.firstinspires.ftc.ftccommon.external.OnCreateMenu
org.firstinspires.ftc.ftccommon.external.OnDestroy
org.firstinspires.ftc.ftccommon.external.WebHandlerRegistrar

Open FTC Docs

External Libraries in OnBot Java and Blocks

FTC Docs·BSD 3-Clause

Blocks and OnBot Java programmers can use external libraries, starting with SDK 7.0 released for the Freight Frenzy season. This capability previously existed for programmers using Android Studio.

An external library is a collection of specialized software ready for public use, and typically available from a website or repository, called a ‘repo’. You don’t need to know its inner workings, just what it does and how to use it.

This beginner-level tutorial shows how to incorporate a library’s features into your Op Modes, and provides simple examples. It does not teach Java.

Many thanks to Liz Looney (https://github.com/lizlooney) who developed this capability, along with myBlocks and many other useful features of the software.

Note: This new capability exists for a Robot Controller (RC) running Android 7 & and higher. Moto G 2nd Gen and Moto G 3rd Gen RC phones cannot use this feature.

Open FTC Docs

External Libraries in OnBot Java and Blocks > Step 1 - Select library, get archive file

FTC Docs·BSD 3-Clause

There are hundreds of code libraries available on the internet. In Step 1, you find a library with specialized functions (methods) that you want to use. Start with a web search, or get suggestions from other teams.

It’s best to choose a repo with a well documented interface. Review its documentation or API, learn what the methods can do, and learn about inputs required and output provided.

If that’s something you want to use, then try to find the .jar or .aar file. The .jar suffix means Java Archive and .aar means a similar format called Android Archive. This is a compressed file containing the entire collection of code that you want, in a single file. It’s similar to a zip file that you may have used for general web downloads.

If you’re having trouble locating that .jar file, or if you’re not sure how to use that library, you are encouraged to contact the repo owner or developer. They often enjoy hearing how programmers plan to use their code, and would be happy to help you get started. Don’t be intimidated, they are often willing to help.

Then just download that .jar or .aar file to local storage such as your laptop or to a team Google drive.

Open FTC Docs

External Libraries in OnBot Java and Blocks > Real-world libraries

FTC Docs·BSD 3-Clause

External Libraries have unique content and structure. Each may pose special challenges as you try to use it in robot code. Communication with the library developer will be very helpful, perhaps essential.

Ideally, the library’s .jar or .aar file encompasses all the classes you’ll need, without external dependencies. A good example is EasyOpenCV, designed and ready for use. See the simple instructions here (https://github.com/OpenFTC/EasyOpenCV).

General external libraries might involve a longer journey. For example, Apache Commons (https://commons.apache.org/) is a vast public repo, basically a library of libraries, focused on the Java programming language. Complications can arise even when choosing a simple math-only library.

Apache libraries are organized into Modules, typically each with one or more .jar files. It may not be sufficient to upload only the .jar file that seems to contain the class and methods you want to use.

If the library code refers to a class not contained in that .jar file, OnBot Java’s auto-complete feature may eventually throw a ‘class not found’ exception, causing your RC app to crash. The exception triggered by this ‘hidden dependency’ may occur within minutes or hours, whenever OBJ encounters the ‘missing’ class – even if your OpMode does not directly or indirectly use that class. After that point, your RC app will not operate. It can operate again only by manually deleting the .jar file and its associated folder, directly on the RC device.

Starting over, you can find and upload the .jar file containing the ‘missing’ class. But that may expose further dependencies, requiring more .jar files.

Also, be aware that the SDK already contains some common Apache classes. OnBot Java may detect this duplication, preventing upload of your .jar file. On the bright side, your desired methods should already be available!

So, be prepared for these and other challenges that may arise. Again, it’s helpful to communicate with the library developer where possible.

Open FTC Docs

FTC SDK API > com.qualcomm.robotcore.hardware > AnalogInputController

FTC SDK API·BSD 3-Clause

Interface for working with Analog Controllers

Open FTC SDK API

External Libraries in OnBot Java and Blocks > User Training & Documentation

FTC Docs·BSD 3-Clause

For Step 3B or Step 3C, your Blocks users must be taught how to use the new myBlocks or the new pass-through Blocks. That’s your job, as the Java developer who implemented this feature.

Start with good documentation. For myBlocks, use the existing tools to make helpful labels (for input parameters), clear tooltips and detailed comments. The comments appear in a text box that expands after clicking the blue question-mark icon on that Block. Tell your users it’s there.

(Figure: myBlock documented using comment, tooltip and input labels)

Meet with your team’s Blocks programmer(s) to explain the new features. Consider writing a short description, for their future reference. Encourage users to give you feedback, to improve your code. Congratulations, you are now a Java developer!

Open FTC Docs

Introduction > Notes on Java

FTC Docs·BSD 3-Clause

This tutorial builds myBlocks with OnBot Java,

a programming tool running on the Control Hub or Robot Controller (RC) phone. Students already using :ref:Android Studio <programming_resources/android_studio_java/android-studio-tutorial:android studio programming tutorial> can easily follow the same programming.

This tutorial does not teach

Java (https://en.wikipedia.org/wiki/Java_(programming_language)) or OnBot Java (OBJ), beyond the bare minimum needed for basic myBlocks.

Open FTC Docs

FTC SDK API > org.firstinspires.ftc.robotcore.external.android.util > Size

FTC SDK API·BSD 3-Clause

Immutable class for describing width and height dimensions in integer valued units. Backported from API21, where it was introduced, to here, where we need to support API19.

Open FTC SDK API

FTC SDK API > com.qualcomm.robotcore.hardware.configuration > Utility

FTC SDK API·BSD 3-Clause

Utility is an old general purpose utility class.

Open FTC SDK API

FTC SDK API > com.qualcomm.robotcore.hardware > ServoController

FTC SDK API·BSD 3-Clause

Interface for working with Servo Controllers Different servo controllers will implement this interface.

Open FTC SDK API

External Libraries in OnBot Java and Blocks > Benefits

FTC Docs·BSD 3-Clause

Obviously this External Libraries feature provides advanced functions previously available only to Android Studio teams.

Secondly, more of your team members can continue programming the robot in Blocks. Meanwhile other students (like you), if they want to, can advance their Java skills and still contribute to the team’s actual robot programming.

Often, teams have one student who has moved far ahead with their Java skills, and becomes the team programmer – the only programmer. Then nobody else has the chance to learn and contribute basic programming.

This feature can allow a new arrangement: “nobody is left out, and nobody is held back”.

As a third benefit, judges love to hear about Outreach. For example your team could develop useful Blocks for beginner teams. Or, you share ideas and tips with other advanced teams who are doing the same kind of development. And, you are encouraged to communicate with library developers. This is a good opportunity for real-world interaction with specialists: sharing your needs, and receiving expert guidance. Scientists, engineers, doctors, entrepreneurs – nobody needs to reinvent the wheel. Professional life is built on these interactions.

Open FTC Docs