SCDS/FtcRobotControllerSDK
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update internal links

Westside Robotics
2021-11-15 16:30:32 -08:00
parent 520e36f863
commit f71ecbc77b
1 changed files with 15 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
Custom-FTC-Blocks-(myBlocks).md

@ -1,7 +1,7 @@
# Introduction to myBlocks # Introduction to myBlocks
This tutorial shows how to make **custom FTC Blocks**, to be used in regular Blocks programs. These **"myBlocks"** are programmed in Java, with OnBotJava or Android Studio. This tutorial shows how to make **custom FTC Blocks**, to be used in regular Blocks programs. These **"myBlocks"** are programmed in Java, with OnBot Java or Android Studio.
<p align="center">[[/images/Custom-FTC-Blocks-(myBlocks)/a0100-introSample.png|sample myBlock, return void]] <p align="center">[[/images/Custom-FTC-Blocks-(myBlocks)/a0100-introSample.png|sample myBlock, return void]]
<br><i><b>sample myBlock: operate a servo, no value returned</b></i><p> <br><i><b>sample myBlock: operate a servo, no value returned</b></i><p>
@ -16,8 +16,8 @@ Also, myBlocks programming allows some team members to begin learning and using
Hats off to Google engineer [Liz Looney](https://github.com/lizlooney) for this major development! Hats off to Google engineer [Liz Looney](https://github.com/lizlooney) for this major development!
### Notes on Java ### Notes on Java
- This tutorial builds myBlocks with [OnBotJava](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/OnBot-Java-Tutorial), a programming tool running on the Control Hub or Robot Controller (RC) phone. Students already using [Android Studio](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Android-Studio-Tutorial) can easily follow the same programming. - This tutorial builds myBlocks with [OnBot Java](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/OnBot-Java-Tutorial), a programming tool running on the Control Hub or Robot Controller (RC) phone. Students already using [Android Studio](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Android-Studio-Tutorial) can easily follow the same programming.
- This tutorial does <u>not</u> teach [Java](https://en.wikipedia.org/wiki/Java_(programming_language)) or OnBotJava (OBJ), beyond the bare minimum needed for basic myBlocks. - This tutorial does <u>not</u> teach [Java](https://en.wikipedia.org/wiki/Java_(programming_language)) or OnBot Java (OBJ), beyond the bare minimum needed for basic myBlocks.
<p align="right"><i>[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)]]</i><p> <p align="right"><i>[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)]]</i><p>
@ -25,7 +25,7 @@ Hats off to Google engineer [Liz Looney](https://github.com/lizlooney) for this
Start with a simple myBlock that creates a greeting "Hello World" (of course!). Start with a simple myBlock that creates a greeting "Hello World" (of course!).
Open a Chrome browser connected via Wi-Fi to a Control Hub or RC phone. Go to the address **http://192.168.43.1:8080** (CH) or **http://192.168.49.1:8080** (RC), and click the **OnBotJava** tab. Open a Chrome browser connected via Wi-Fi to a Control Hub or RC phone. Go to the address **http://192.168.43.1:8080** (CH) or **http://192.168.49.1:8080** (RC), and click the **OnBot Java** tab.
> <i>Note: a computer can usually connect to only <u>one</u> Wi-Fi network at a time. To follow this tutorial while programming, first allow this single web page to load completely, then connect to the Control Hub or RC phone. If you need internet <u>and</u> FTC programming together, connect an Ethernet cable to an internet router **or** try adding a USB Wi-Fi dongle.</i> > <i>Note: a computer can usually connect to only <u>one</u> Wi-Fi network at a time. To follow this tutorial while programming, first allow this single web page to load completely, then connect to the Control Hub or RC phone. If you need internet <u>and</u> FTC programming together, connect an Ethernet cable to an internet router **or** try adding a USB Wi-Fi dongle.</i>
@ -85,7 +85,7 @@ The method contains only one line of instruction, on Line 15: **three text items
That's it for the Java! Click the wrench icon to **_Build Everything_** including your new class. If there are error messages, read carefully and fix any mistakes. When you see "Build Successful!", your new myBlock is ready to use. That's it for the Java! Click the wrench icon to **_Build Everything_** including your new class. If there are error messages, read carefully and fix any mistakes. When you see "Build Successful!", your new myBlock is ready to use.
> <i>Note: this tutorial intends for you to **manually type** the Java code above. OnBotJava helps by suggesting some code as you type, and by entering import statements when classes are used. Android Studio helps even more. If you require pre-typed text of this example, click [here](https://github.com/WestsideRobotics/FTCmyBlocks/blob/main/Examples/SampleMyBlocks_v00.java).</i> > <i>Note: this tutorial intends for you to **manually type** the Java code above. OnBot Java helps by suggesting some code as you type, and by entering import statements when classes are used. Android Studio helps even more. If you require pre-typed text of this example, click [here](https://github.com/WestsideRobotics/FTCmyBlocks/blob/main/Examples/SampleMyBlocks_v00.java).</i>
<p align="right"><i>[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)]]</i><p> <p align="right"><i>[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)]]</i><p>
@ -119,11 +119,11 @@ In the **```key```** socket, type **A greeting for you**. At the **```text```**
<p align="center">[[/images/Custom-FTC-Blocks-(myBlocks)/a0200-Hello-run-screenshot-circle.png|DS screenshot]]<p> <p align="center">[[/images/Custom-FTC-Blocks-(myBlocks)/a0200-Hello-run-screenshot-circle.png|DS screenshot]]<p>
<br>**<i>Congratulations!</i>** You are now an OnBotJava programmer and myBlocks creator. <br>**<i>Congratulations!</i>** You are now an OnBot Java programmer and myBlocks creator.
> <i>For extra fun: try the **Telemetry.speak** Block, followed by a 1500 millisecond **```.sleep```** Block. You can learn more about DS spoken telemetry at [this separate tutorial](https://github.com/WestsideRobotics/FTC-DS-Speech/wiki).</i> > <i>For extra fun: try the **Telemetry.speak** Block, followed by a 1500 millisecond **```.sleep```** Block. You can learn more about DS spoken telemetry at [this separate tutorial](https://github.com/WestsideRobotics/FTC-DS-Speech/wiki).</i>
This tutorial has three more sections with myBlocks guidelines, followed by **six examples** for you to re-type in OnBotJava and test in Blocks. Enjoy! This tutorial has three more sections with myBlocks guidelines, followed by **six examples** for you to re-type in OnBot Java and test in Blocks. Enjoy!
<p align="right"><i>[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)]]</i><p> <p align="right"><i>[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)]]</i><p>
@ -138,7 +138,7 @@ The required **annotation** ```@ExportToBlocks``` has optional fields, which may
### Comment ### Comment
- The **comment** text appears in a balloon when the Blocks user clicks the blue question-mark icon. Tell the user **how to use your myBlock**. - The **comment** text appears in a balloon when the Blocks user clicks the blue question-mark icon. Tell the user **how to use your myBlock**.
- Must be entered on a **single line**, with no 'line breaks'. This requirement can be met by **joining text strings**; an example is [[below|https://github.com/WestsideRobotics/FTCmyBlocks/wiki/hardware-example-control-a-servo]]. - Must be entered on a **single line**, with no 'line breaks'. This requirement can be met by **joining text strings**; an example is [[below|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)/#hardware-example-control-a-servo]].
- The blue icon will appear only if a custom comment is specified. The Blocks user can add and remove the blue icon, and can edit its text in the (re-sizeable) balloon. - The blue icon will appear only if a custom comment is specified. The Blocks user can add and remove the blue icon, and can edit its text in the (re-sizeable) balloon.
### Tooltip ### Tooltip
@ -177,7 +177,7 @@ Do not type or run the following myBlock example. Its dummy inputs simply illus
Notice that the Java **parameters** ```uno```, ```parola``` and ```verita``` have **myBlock labels** ```One```, ```Word``` and ```Truth```. They are allowed to be different. Notice that the Java **parameters** ```uno```, ```parola``` and ```verita``` have **myBlock labels** ```One```, ```Word``` and ```Truth```. They are allowed to be different.
The **comment** field explains this myBlock to the Blocks user, who can edit or delete the comment. Only for display here, this sample text appears on multiple lines; normally it must be typed as a single line of text or as joined quotes (example [[below|https://github.com/WestsideRobotics/FTCmyBlocks/wiki/hardware-example-control-a-servo]]). The **comment** field explains this myBlock to the Blocks user, who can edit or delete the comment. Only for display here, this sample text appears on multiple lines; normally it must be typed as a single line of text or as joined quotes (example [[below|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)/#hardware-example-control-a-servo]]).
A myBlock **tooltip** should be brief. Note: the four tooltips don't all appear at the same time; each appears with a mouseover. One is custom, three are auto-generated based on input type. A myBlock **tooltip** should be brief. Note: the four tooltips don't all appear at the same time; each appears with a mouseover. One is custom, three are auto-generated based on input type.
@ -209,7 +209,7 @@ In any case, consider adding **versions** to your myBlock names, such as myGreet
Keep the class name **short and generic**, such as MyBlocks, SampleMyBlocks, Team8604MyBlocks, DrivingMyBlocks, etc. It will contain all or many related myBlocks, not just one myBlock per the simple examples above. Keep the class name **short and generic**, such as MyBlocks, SampleMyBlocks, Team8604MyBlocks, DrivingMyBlocks, etc. It will contain all or many related myBlocks, not just one myBlock per the simple examples above.
In that single class, each myBlock method must appear <u>after</u> its own annotation ```@ExportToBlocks```. That class may contain other methods that are not myBlocks; omit the annotation before any non-myBlock methods. Such methods might be used to initialize variables, or might be (shared) submethods called by one or more myBlocks. An example is shown [[far below|https://github.com/WestsideRobotics/FTCmyBlocks/wiki/example-non-myblock-methods]]. In that single class, each myBlock method must appear <u>after</u> its own annotation ```@ExportToBlocks```. That class may contain other methods that are not myBlocks; omit the annotation before any non-myBlock methods. Such methods might be used to initialize variables, or might be (shared) submethods called by one or more myBlocks. An example is shown [[far below|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)/#example-non-myblock-methods]].
This tutorial has covered these basic requirements so far: This tutorial has covered these basic requirements so far:
- create/store in **org.firstinspires.ftc.teamcode** folder/package - create/store in **org.firstinspires.ftc.teamcode** folder/package
@ -218,7 +218,7 @@ This tutorial has covered these basic requirements so far:
- method must be **public** and **static** (must not be <i>abstract</i>) - method must be **public** and **static** (must not be <i>abstract</i>)
- replace myBlocks after external edits - replace myBlocks after external edits
The rest of this tutorial gives **examples** that you can **re-type in OnBotJava** and **test in Blocks**. Try making changes and adding features! The rest of this tutorial gives **examples** that you can **re-type in OnBot Java** and **test in Blocks**. Try making changes and adding features!
<p align="right"><i>[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)]]</i><p> <p align="right"><i>[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)]]</i><p>
@ -328,7 +328,7 @@ So, what was the danger? A programmer might naturally place Line 15 **inside**
Or, a programmer might use Line 15 to **replace** Line 29, since they "do the same thing". But the object **myStopwatch** is needed at Line 24 also, for telemetry. Moving the telemetry to be **after** Line 29 does not help. If the operator has not yet pressed gamepad button X, the object does not exist and the program will crash. Or, a programmer might use Line 15 to **replace** Line 29, since they "do the same thing". But the object **myStopwatch** is needed at Line 24 also, for telemetry. Moving the telemetry to be **after** Line 29 does not help. If the operator has not yet pressed gamepad button X, the object does not exist and the program will crash.
When you clicked "Build Everything" in OnBotJava, all of the code in your SampleMyBlocks class was processed. That included creating the object myStopwatch, which became available for any method in that class. It was not necessary to declare it inside the myBlock method. In this case, it **needed** to be outside the method. When you clicked "Build Everything" in OnBot Java, all of the code in your SampleMyBlocks class was processed. That included creating the object myStopwatch, which became available for any method in that class. It was not necessary to declare it inside the myBlock method. In this case, it **needed** to be outside the method.
Here's the myBlock in a repeat loop, with its **comment** and **tooltip**: Here's the myBlock in a repeat loop, with its **comment** and **tooltip**:
@ -336,7 +336,7 @@ Here's the myBlock in a repeat loop, with its **comment** and **tooltip**:
Again, the comment field is the only way to communicate with future users of your myBlock. They cannot see your Java code or its Java comments. Keep your myBlocks interface simple, and the instructions clear. Again, the comment field is the only way to communicate with future users of your myBlock. They cannot see your Java code or its Java comments. Keep your myBlocks interface simple, and the instructions clear.
> <i>Note: this tutorial intends for you to **manually type** the Java code above. OnBotJava helps by suggesting some code as you type, and by entering import statements when classes are used. Android Studio helps even more. If you require pre-typed text of this example, click [here](https://github.com/WestsideRobotics/FTCmyBlocks/blob/main/Examples/SampleMyBlocks_v03.java). The linked copy includes more Java comments, omitted above to focus on the Java code. Also not shown are the package and import statements.</i> > <i>Note: this tutorial intends for you to **manually type** the Java code above. OnBot Java helps by suggesting some code as you type, and by entering import statements when classes are used. Android Studio helps even more. If you require pre-typed text of this example, click [here](https://github.com/WestsideRobotics/FTCmyBlocks/blob/main/Examples/SampleMyBlocks_v03.java). The linked copy includes more Java comments, omitted above to focus on the Java code. Also not shown are the package and import statements.</i>
<p align="right"><i>[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)]]</i><p> <p align="right"><i>[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)]]</i><p>
@ -391,7 +391,7 @@ Write and read actions can happen in the same OpMode or **different OpModes**, a
- A **dedicated log file** reports key sensor data in a custom format, with optional time-stamps. For program development and debugging, this could be more efficient than working with the large standard logs or Match Logs. - A **dedicated log file** reports key sensor data in a custom format, with optional time-stamps. For program development and debugging, this could be more efficient than working with the large standard logs or Match Logs.
The Java code for this example is available [here](https://github.com/WestsideRobotics/FTCmyBlocks/blob/main/Examples/SampleMyBlocks_v05.java), with **extensive comments** that explain some unfamiliar Java expressions. The code can be copied and pasted directly into OnBotJava or Android Studio. The Java code for this example is available [here](https://github.com/WestsideRobotics/FTCmyBlocks/blob/main/Examples/SampleMyBlocks_v05.java), with **extensive comments** that explain some unfamiliar Java expressions. The code can be copied and pasted directly into OnBot Java or Android Studio.
> <i>Programming tip: Instead of memorizing every possible Java command, programmers often study and modify existing code for a similar task. Unfamiliar commands are explored with an internet search, reference book, at the [FTC Javadoc reference](https://javadoc.io/doc/org.firstinspires.ftc), or at the official [Oracle Javadoc](https://docs.oracle.com/javase/7/docs/api/).</i> > <i>Programming tip: Instead of memorizing every possible Java command, programmers often study and modify existing code for a similar task. Unfamiliar commands are explored with an internet search, reference book, at the [FTC Javadoc reference](https://javadoc.io/doc/org.firstinspires.ftc), or at the official [Oracle Javadoc](https://docs.oracle.com/javase/7/docs/api/).</i>
@ -465,7 +465,7 @@ Here are some tips for efficiency, from the developer Liz Looney:
3. MyBlocks programming allows some team members to begin learning and using Java, contributing valuable new features. The other team members can continue learning and working in Blocks, producing the team's official code. Nobody is held back, or left behind. 3. MyBlocks programming allows some team members to begin learning and using Java, contributing valuable new features. The other team members can continue learning and working in Blocks, producing the team's official code. Nobody is held back, or left behind.
4. MyBlocks can be created with **OnBotJava**, which runs on the RC phone or Control Hub. Building and testing are very fast. Many FTC teams do not have easy access to Android Studio, for reasons including school computers that prevent software installation. 4. MyBlocks can be created with **OnBot Java**, which runs on the RC phone or Control Hub. Building and testing are very fast. Many FTC teams do not have easy access to Android Studio, for reasons including school computers that prevent software installation.
5. By developing and sharing myBlocks, experienced FTC teams could **help new teams** in a more direct way, beyond simply posting a link to their Java library. The FTC community might ultimately benefit from a curated repository for tested, well documented myBlocks. Perhaps the "Blocks Store"? 5. By developing and sharing myBlocks, experienced FTC teams could **help new teams** in a more direct way, beyond simply posting a link to their Java library. The FTC community might ultimately benefit from a curated repository for tested, well documented myBlocks. Perhaps the "Blocks Store"?