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

unknown error

WestsideRobotics
2022-06-08 17:02:57 -07:00
parent 9e85ff40bb 0e73e46956
commit d6b91a43c1
3 changed files with 764 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

344
Datalogging-Part-2,-Custom-Data.md Normal file

@ -0,0 +1,344 @@
## Introduction
This tutorial shows how to customize the sample OpMode for FTC Datalogging.
This is **Part 2** of a 4-part series on Datalogging. It presumes you completed [**Part 1**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging), running the sample OpMode and charting its data.
Although aimed at **OnBot Java** users, these instructions allow **Android Studio** programmers to use the same Java code.
Datalogging can be made available to **FTC Blocks** users, by creating myBlocks in OnBot Java. MyBlocks are covered in a separate tutorial at the FTC Wiki [here](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)).
Many thanks to [@Windwoes](https://github.com/Windwoes) for developing this valuable tool.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Configure Devices
Start by adding some physical devices to your 'robot'. For convenience, the sample OpMode used only internal or software data sources; the 'robot' was just a bare REV Hub.
<p align="center">[[/images/Datalogging-2/010-testbed.png|010-testbed]]
This tutorial will log data from 5 basic devices, one for each of the 5 REV Hub **port sections**:
- DC Motor with encoder
- Conventional servo (not continuous rotation servo)
- REV touch sensor in Digital port
- REV potentiometer in Analog port
- REV color sensor in I2C port
You may connect only one or a few of these, based on availability -- this exercise simply shows how to customize **any** basic input.
<i>Side note: a typical servo does not provide feedback (data) to the controller. A servo is included here because a user might want to chart its commanded position versus some other data source. In this example, the datalog field is `grabberServo.getPosition()` which is simply the servo's last commanded position. Datalog users should think ahead to the desired chart, which might include robot inputs **and** outputs.</i>
If you already have additional devices connected to the Hub, you may leave them in place.
In the DS app, or on the RC phone, open **Configure Robot** and add these datalogging devices. You may use the following names, or keep any existing configured names:
- DC Motor name: lifter
- Servo name: grabber
- Touch Sensor name: sensorTouch
- Potentiometer name: sensorPot
- Color Sensor name: sensorColor
Note that the REV Touch Sensor is an "n+1" device; configure it in the **higher** of two Digital port numbers marked on the Hub label. The REV Potentiometer is an "n" device; configure it as "Analog Input" in the **lower** of two marked Analog port numbers. Also note the REV Color Sensor **V3** has its own device type listed.
When finished, save this as the active configuration.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Software Overview
[**ConceptDatalogger.java**](https://github.com/FIRST-Tech-Challenge/WikiSupport/blob/master/SampleOpModes/Datalogging/ConceptDatalogger.java) is the sample OpMode that the user runs from the Driver Station. It specifies and collects certain robot data to be logged and ultimately charted.
This Part 2 tutorial shows how to customize the sample OpMode, to collect other robot data.
After working on these or any other OBJ files, it's a good idea to right-click and Download them again to the laptop for safekeeping. This backup can be done periodically or at the end of your work session.
It's also helpful to right-click and Copy, Paste and Rename major revisions of edited files, to save previous/working versions under modified filenames such as v02, v03, etc.
The sample OpMode, and custom versions that you will create, use commands/methods provided in the Datalogger class. That class exists in a [different Java file](https://github.com/FIRST-Tech-Challenge/WikiSupport/blob/master/SampleOpModes/Datalogging/Datalogger.java) that is typically **not edited** by the user. Its inner workings are not covered in this tutorial series.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Open New Java File
Connect the programming laptop to the Robot Controller device (Control Hub or RC phone) as usual.
In OnBot Java, right-click on ConceptDatalogger.java and choose Copy. Then right-click anywhere and choose Paste, then click OK; this creates a file named ConceptDatalogger_Copy.java.
Now right-click the copy, and choose Rename. Enter the name of your new OpMode: DatalogExample_v01.java. Click OK.
Click on this new filename to begin editing.
At line 28, change the OpMode display name from "Concept Datalogger 01" to "Datalog Example v01".
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Declare Hardware
You will now set up the hardware devices, in this OpMode DatalogExample_v01.java.
First remove the hardware declarations used in the original sample (unless you are using one of these again). Find and delete the 2 separate lines for the voltage sensor, and the 5 separate lines for the IMU:
```java
VoltageSensor battery;
battery = hardwareMap.voltageSensor.get("Control Hub");
```
```java
BNO055IMU imu;
imu = hardwareMap.get(BNO055IMU.class, "imu");
BNO055IMU.Parameters parameters = new BNO055IMU.Parameters();
parameters.angleUnit = BNO055IMU.AngleUnit.DEGREES;
imu.initialize(parameters);
```
Replace those with declarations for your new hardware. First place the object instantiations after "public class" and before @Override:
```java
Dcmotor lifterMotor;
Servo grabberServo;
TouchSensor myTouchSensor;
AnalogInput myPotSensor;
ColorSensor myColorSensor;
```
Now place the object assignments at the beginning of the "runOpMode()" section, using the device names (in quotes) from your Configuration file:
```java
lifterMotor = hardwareMap.get(DcMotor.class, "lifter");
grabberServo = hardwareMap.get(Servo.class, "grabber");
myTouchSensor = hardwareMap.get(TouchSensor.class, "sensorTouch");
myPotSensor = hardwareMap.get(AnalogInput.class, "sensorPot");
myColorSensor = hardwareMap.get(ColorSensor.class, "sensorColor");
```
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Clean up Class Imports
You may have noticed that OnBot Java **automatically added** the class `import` statements for the 5 new hardware items:
```java
import com.qualcomm.robotcore.hardware.DcMotor;
import com.qualcomm.robotcore.hardware.Servo;
import com.qualcomm.robotcore.hardware.TouchSensor;
import com.qualcomm.robotcore.hardware.AnalogInput;
import com.qualcomm.robotcore.hardware.ColorSensor;
```
OnBot Java does not automatically **remove** unused import statements. If you deleted all IMU and VoltageSensor declarations (2+5 Java lines listed above), you may also delete the corresponding class imports:
```java
import com.qualcomm.hardware.bosch.BNO055IMU;
import com.qualcomm.robotcore.hardware.VoltageSensor;
```
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Set Up Data Fields
To create your custom datalog, the first step is **declaring the data fields**. These will be the **columns** of the CSV file and spreadsheet, after the automatic timestamp.
Near the end of this DatalogExample_v01.java OpMode, see the Datalog class definition. Here the previous fields were declared and labeled:
```java
public Datalogger.GenericField opModeStatus = new Datalogger.GenericField("OpModeStatus");
public Datalogger.GenericField loopCounter = new Datalogger.GenericField("Loop Counter");
public Datalogger.GenericField yaw = new Datalogger.GenericField("Yaw");
public Datalogger.GenericField pitch = new Datalogger.GenericField("Pitch");
public Datalogger.GenericField roll = new Datalogger.GenericField("Roll");
public Datalogger.GenericField battery = new Datalogger.GenericField("Battery");
```
You can keep the first two data items if desired. They are generated by this OpMode's code, not by a hardware sensor. Replace or edit the remaining 4 items, using only the configured datalogging devices you added to the Hub. Your new list might read as follows:
```java
public Datalogger.GenericField opModeStatus = new Datalogger.GenericField("OpModeStatus");
public Datalogger.GenericField loopCounter = new Datalogger.GenericField("Loop Counter");
public Datalogger.GenericField motorEncoder = new Datalogger.GenericField("Lifter Enc.");
public Datalogger.GenericField servoPosition = new Datalogger.GenericField("Grabber Pos.");
public Datalogger.GenericField touchPress = new Datalogger.GenericField("Touched");
public Datalogger.GenericField potValue = new Datalogger.GenericField("Pot. Value");
public Datalogger.GenericField totalLight = new Datalogger.GenericField("Total Light");
```
With the above edits, you have specified each data field **name** and its CSV column **heading**.
You did not need to research and specify the **Java type** of each data field. This will be handled automatically by the `Datalogger.java` class.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Set Field Order
Further down in the Datalog class definition, the method `setFields()` gives the order that fields are arranged in the log file. This will be the **order of columns** in the CSV spreadsheet file.
The new version might read as follows, subject to the actual fields you defined above, and the order you prefer:
```java
.setFields(
opModeStatus,
loopCounter,
motorEncoder,
servoPosition,
touchPress,
potValue,
totalLight
)
```
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Collect Data for Logging
As the OpMode runs, collecting log data is done with the `datalog` object, which is an instance of the Datalog class.
For the voltage sensor, a single value was assigned to `datalog.battery`:
```java
datalog.battery.set(battery.getVoltage());
```
For the IMU rotations, one value from the `orientation` array was assigned to `datalog.yaw`. Likewise for `datalog.pitch` and `datalog.roll`:
```java
Orientation orientation = imu.getAngularOrientation();
datalog.yaw.set(orientation.firstAngle);
datalog.pitch.set(orientation.secondAngle);
datalog.roll.set(orientation.thirdAngle);
```
The above 1+4 lines can be deleted, along with the import statement for Orientation.
In this new OpMode, the added devices' data is logged as follows:
```java
datalog.motorEncoder.set(lifterMotor.getCurrentPosition());
datalog.servoPosition.set("%.2f", grabberServo.getPosition());
datalog.touchPress.set(myTouchSensor.isPressed());
datalog.potValue.set("%.1f", myPotSensor.getVoltage());
datalog.totalLight.set(myColorSensor.alpha());
```
Just to illustrate, two of these data fields have been optionally **formatted**, using the same codes as used for telemetry. Here, the servo position will be logged with 2 decimal places, and the potentiometer voltage will be logged with 1 decimal place.
Such codes can be omitted. The `Datalogger.java` class uses a **default format** of "%.3f" for data types `float` and `double`. The defaults can be edited in that file, if desired.
As noted far above, the servo method `getPosition()` does not provide feedback from the servo device. It simply reports the servo's last **commanded** position.
The DC motor method `getCurrentPosition()` does provide actual feedback from the motor encoder, if properly connected.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Post Data to the Log
Finally, post the data to the log, with a timestamp. This is done with a single command; no editing is needed:
```java
datalog.writeLine();
```
**Not every field** of the datalog must be collected/filled with each call to `writeLine()`. Any non-collected field will be populated with its **last value**.
Between calls to `writeLine()`, the **order** of collecting datalog fields does not matter. The data will be posted in the correct order, defined by the user in the `setFields()` method.
The datalog receives the timestamp of the call to `writeLine()`, **not** the time of collecting the data (e.g. `datalog.motorEncoder.set()`).
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Telemetry
Edit the telemetry section as desired. For example:
```java
telemetry.addData("Lifter Motor Encoder", datalog.motorEncoder);
telemetry.addData("Grabber Position (commanded)", datalog.servoPosition);
telemetry.addData("Touched", datalog.touchPress);
telemetry.addData("Pot. Voltage", datalog.potValue);
telemetry.addData("Color Sensor Alpha (total light)", datalog.totalLight);
telemetry.update();
```
Again, **all** datalog fields are saved as **text** in the CSV file. Thus, Driver Station telemetry can display a logged value in its logged format only. See above for formatting numeric log values.
Numeric format codes do not apply for telemetry here, since the log values are no longer numeric. Not to worry, charting software interprets such values as numeric!
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Testing
That's all the editing needed, to add the new devices.
Lastly, you could make the motor and servo **move** with simple gamepad input, inside the "for() loop".
```java
lifterMotor.setPower(-gamepad1.left_stick_y);
grabberServo.setPosition(gamepad1.left_trigger);
```
Click the wrench icon "Build Everything". Correct any syntax errors noted, and repeat the build. Wait for confirmation, "Build Successful".
To compare with your own code developed above, click to see a [complete DatalogExample_v01.java](https://github.com/FIRST-Tech-Challenge/WikiSupport/blob/master/SampleOpModes/Datalogging/DatalogExample_v01.java) OpMode.
Time to test! On a paired Driver Station with gamepad, select the TeleOp OpMode listed as "Datalog Example v01". Touch INIT and Start. While observing the live telemetry on the DS screen, move and manipulate the robot's devices to generate data. Do this for about 20-30 seconds, then touch the square Stop button.
The datalog is now created, listed in OnBot Java with a Chrome browser refresh. Using the next steps from the [Part 1 tutorial](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging#transfer-datalog-to-laptop), here are sample charts using the new hardware:
<br>
<p align="center">[[/images/Datalogging-2/050-grabber-chart.png|050-grabber-chart]]
<br>
<p align="center">[[/images/Datalogging-2/060-grab+pot-chart.png|060-grab+pot-chart]]
<br>
<p align="center">[[/images/Datalogging-2/070-lifter+light-chart.png|070-lifter+light-chart]]
<br><p>After this is working well, you may continue to customize the OpMode for your needs. Work step-by-step, adding one feature at a time.
This example OpMode uses a "for() loop" with loop counter "i". This could be converted to the more common "while() loop", with various ways to end the loop.
Ultimately you could work this code into your existing Autonomous or TeleOp OpModes, or into **test versions** of those programs. Consider a Boolean toggle that turns datalogging on or off.
With each new major version, right-click and Copy, Paste and Rename, to save previous/working versions under modified filenames such as v02, v03, etc. It's also good to right-click and Download to the laptop periodically.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Data Evaluation
Excel and Google Sheets offer many more data evaluation features, beyond the scope of this tutorial. You are encouraged to learn and explore those features, ultimately providing a better understanding of robot performance. This may help you with troubleshooting, optimization and robot design.
As noted far above, you may want to datalog robot inputs **and** outputs, plotting them on X and Y axes. This may help identify cause and effect.
Datalogging can also be used to evaluate **Vuforia** and **TensorFlow** data from a camera. A "rogue" input or recognition might pass too quickly to observe with Driver Station telemetry, but Datalogging can display the actual events.
For example, TensorFlow Object Detection (TFOD) methods provide recognition **labels**, **confidence** values, and Bounding Box pixel **coordinates**. Combined with the automatic timestamps, this data could help troubleshoot and optimize the Autonomous programmed decision process:
- Was the Bounding Box suspiciously large?
- Was the first recognition "real"?
- Is the 10th consecutive recognition more trustworthy?
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Summary
Teams using FTC Blocks and OnBot Java can use Datalogging to solve problems and improve robot performance. Teams using Android Studio can use all the same Java code described above.
FTC students will benefit from this valuable skill, widely used in professional fields such as engineering, scientific research, medicine, social media and marketing, business management, and many more.
You are encouraged to submit and describe other examples that worked for you.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
===========
This is Part 2 of a 4-part series on FTC Datalogging.
[**Part 1**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging) shows how to run a sample OpMode and chart its data.
[**Part 3**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging-Part-3,-RC-File-Transfer) shows Android Studio users how to transfer datalog files from the RC device to a computer. (This isn't needed with OnBot Java, where datalogs appear on-screen for easy Download.)
[**Part 4**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging-Part-4,-Java-Learning-Exercise) describes the inner workings of a **different**, much simpler Datalogging class. It's strictly a Java learning exercise, showing basic steps to log robot data on the RC device. It does not require familiarity with Parts 1 and 2.
***
<i>Questions, comments and corrections to westsiderobotics@verizon.net</i>

162
Datalogging-Part-3,-RC-File-Transfer.md Normal file

@ -0,0 +1,162 @@
## Introduction
This basic tutorial shows some ways to transfer datalog or other files from the FTC Robot Controller (Control Hub or RC phone) to a desktop or laptop computer.
Manually transferring datalog files from the RC device will be of most interest to **Android Studio** users. This isn't needed with OnBot Java, where datalogs can appear on-screen for easy Download.
Another simple way to transfer files is with a USB thumb drive, not covered here.
This article is **Part 3** of a 4-part series on Datalogging. [**Part 1**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging) shows how to run a **sample OpMode** and chart its data. [**Part 2**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging-Part-2,-Custom-Data) shows how to **customize** the sample OpMode for logging your own robot data of interest.
[**Part 4**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging-Part-4,-Java-Learning-Exercise) describes the inner workings of a **different**, much simpler Datalogging class. It's strictly a Java learning exercise, showing basic steps to log robot data on the RC device. It does not require familiarity with Parts 1 and 2.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Wired USB cable
The simplest transfer method is to plug the RC device into a computer via USB cable.
- It must be a 'data' cable, not 'charge-only'.
- For Control Hub use the USB-C port, not the Mini USB port.
- Connect the device for file transfer (Media Transfer Protocol or MTP mode).
- on RC phone, swipe down twice to set MTP mode
- Use the computer's file manager to locate the RC source folder.
- Copy-and-paste the datalog or other file to the computer.
- Unplug the USB cable; no need to 'Eject'.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Wireless adb - Set-up
It's possible to connect the RC device wirelessly to a laptop (or desktop with Wi-Fi). The RC device must allow **USB debugging**, which can be turned on in Developer Options.
- Control Hubs allow USB debugging by default.
- For RC phones, follow these steps:
- open Settings and "About phone"
- tap 7 times on "Build number"
- now "Developer Options" will appear under Settings/System/(Advanced)
- turn on USB debugging
- At first connection to a laptop, check the box to allow USB debugging from that computer.
Also, the laptop must have **Android Debug Bridge** or "adb" installed. Installing adb is described many places online, and in the FTC Wiki at [this page](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Managing-a-Control-Hub#connecting-to-the-control-hub-using-wireless-adb).
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Wireless adb - Command Prompt
After completing the above adb set-up steps, click the laptop's Windows 10 or Windows 7 icon at bottom left corner. In its search bar, type `cmd` to open the Windows **Command Prompt** window.
To verify that adb is already installed, type `adb devices`. An error message will appear if adb is not installed; otherwise a list of devices may appear (OK if blank, for now).
To connect a **Control Hub**, type `adb connect 192.168.43.1:5555` at the command prompt, and wait for acknowledgement.
Connecting an **RC phone** via adb can be done in two ways: with Wi-Fi Direct, or with standard Wi-Fi.
- For both methods, plug RC phone into laptop with USB cable
- optional to set file transfer (MTP) mode
- if a pop-up appears, check the box to allow USB Debugging
- at the command prompt, type `adb tcpip 5555`
- wait for message "restarting in TCP mode port: 5555"
- optional to confirm wired connection with `adb devices`
- unplug the USB cable
- **Wi-Fi Direct method:**
- open the FTC RC app
- connect the laptop's Wi-Fi to the RC phone's network, as usual for Blocks/OnBot Java programming
- at the command prompt, type `adb connect 192.168.49.1:5555`
- receive confirmation
- **Standard Wi-Fi method:**
- confirm laptop and phone on the same standard Wi-Fi network
- Airplane Mode off
- get (from Settings) the phone's IP address (e.g. 192.168.1.15)
- type `adb connect 192.168.1.15:5555`, using the phone's actual IP address
- receive confirmation
- For both methods, optional to confirm wireless connection with `adb devices`.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Wireless adb - File Transfer
With adb in place, copying a file from the connected device to your laptop can be done with a single "pull" command. For example:
`adb pull /sdcard/FIRST/Datalogs/myDatalog_001.csv C:\Users\Public\Documents`
The 'source' field is the **filename** on the RC device. The 'target' field is the desired destination **folder** on your laptop.
And yes, it is really that easy. (There's also a "push" command.)
Some notes:
- Uppercase/lowercase is optional, but pay attention to forward- and back-slashes.
- Files with the same name will be overwritten in the target folder. Rename files as needed to avoid this.
- If a folder or file name contains a space (blank character), enclose the entire pathname in double-quotes. For example, "C:\Users\Public\My Documents".
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Wireless transfer with Android Studio
You could transfer files with Android Studio, used here for its **file manager**, not for programming.
These steps are not as fast as "adb pull", but the file manager allows you to see and navigate the source and target folders.
- connect via adb to the Control Hub or RC phone
- open Android Studio (any project)
- click ["Device Explorer"](https://raw.githubusercontent.com/wiki/WestsideRobotics/FTC-Datalogging/images/AS-01-marked.png) at right edge
- in Device Explorer, navigate to the device folder [FIRST/Datalogs](https://raw.githubusercontent.com/wiki/WestsideRobotics/FTC-Datalogging/images/AS-02-marked.png)
- right-click the filename, choose ["Save As..."](https://raw.githubusercontent.com/wiki/WestsideRobotics/FTC-Datalogging/images/AS-03-marked.png)
- at the next window, navigate to the [laptop target folder](https://raw.githubusercontent.com/wiki/WestsideRobotics/FTC-Datalogging/images/AS-04-marked.png), click OK
This [copies the file](https://raw.githubusercontent.com/wiki/WestsideRobotics/FTC-Datalogging/images/AS-05-marked.png) to the laptop target folder, confirmed with [Windows Explorer](https://raw.githubusercontent.com/wiki/WestsideRobotics/FTC-Datalogging/images/AS-06-marked.png).
To **refresh** the directory listing, re-select the RC device from the top pull-down menu, just below the heading "Device File Explorer".
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Summary
This basic tutorial showed some ways to transfer datalog or other files from the FTC Robot Controller (Control Hub or RC phone) to a desktop or laptop computer.
This article did **not** cover:
- portable USB flash drives (thumb drives)
- direct download with connected software such as FTC Blocks or OnBot Java
- methods that require installing third-party apps to the RC device, and in some cases also installing software to the laptop. Some examples are described [here](https://geeknizer.com/transfer-files-between-pc-and-android/) and [here](https://appuals.com/5-methods-to-wirelessly-transfer-files-from-android-to-pc-no-usb/).
You are encouraged to submit and describe other file transfer methods that worked for you.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
------
This article is **Part 3** of a 4-part series on Datalogging.
[**Part 1**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging) shows how to run a **sample OpMode** and chart its data.
[**Part 2**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging-Part-2,-Custom-Data) shows how to **customize** the sample OpMode for logging your own robot data of interest.
[**Part 4**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging-Part-4,-Java-Learning-Exercise) describes the inner workings of a **different**, much simpler Datalogging class. It's strictly a Java learning exercise, showing basic steps to log robot data on the RC device. It does not require familiarity with Parts 1 and 2.
***
<i>Questions, comments and corrections to westsiderobotics@verizon.net</i>

258
Datalogging.md Normal file

@ -0,0 +1,258 @@
## Introduction
This **Part 1** tutorial shows how to use a handy new FTC Datalogging tool: run a sample OpMode and **chart its data**.
<br>
<p align="center">[[/images/Datalogging-1/011-arrows-and-chart.png|011-arrows-and-chart]]
Although aimed at **OnBot Java** users, these instructions allow **Android Studio** programmers to use the same Java code.
Datalogging can be made available to **FTC Blocks** users, by creating myBlocks in OnBot Java. MyBlocks are covered in a separate tutorial at the FTC Wiki [here](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Custom-FTC-Blocks-(myBlocks)).
This tutorial is **Part 1** of a 4-part series on FTC Datalogging. **After** running the sample OpMode and charting its data, see the end of this page for a link to Part 2: customizing the sample OpMode.
Many thanks to [@Windwoes](https://github.com/Windwoes) for developing this valuable tool.
## Software Overview
Two Java files are provided here:
- **Datalogger.java** is the Java class that handles all details of storing the robot data in a datalog file. A typical user will not need to review or edit this file. Its internal code is not described in this tutorial.
- **ConceptDatalogger.java** is the sample OpMode that's run from the Driver Station as usual. It specifies and collects the robot data to be logged and ultimately charted. The OpMode uses, or calls, commands/methods provided in the Datalogger class. This is the file that can be edited by the user.
This tutorial shows how to run ConceptDatalogger "as is". Part 2 of this series shows how to customize the sample OpMode, to collect **other** robot data.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Robot Preparation
Attach a 12V robot battery and power switch to a **Control Hub**, and turn it on.
**Or** use an **Expansion Hub** with RC phone, and open the RC app -- later you will change one line of code from "Control Hub" to (for example) "Expansion Hub 1".
On a paired Driver Station device, open Configure Robot and verify that the **active configuration** contains "imu" on the Hub's I2C Bus 0. It's normally there by default. Any other hardware (motors, servos, sensors) may be present and configured, but are not used in this example.
That's it! The sample OpMode needs only this simple 'robot'. If your Hub is already mounted on a complete robot -- leave it there!
The data to be logged and charted will be generated from 4 sources:
- Inertial Measurement Unit (IMU) built into the Hub
- battery voltage detector in the Hub's controller
- text codes created by the user
- loop counter, generated by the running OpMode
The IMU is a physical sensor defined in the HardwareMap, like other sensors you might use later for Datalogging. The other 3 sources are examples of data generated by the SDK/controller, the user, and the user's code, respectively.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Software Setup
Use **one** of the following ways to transfer the two provided files to the Control Hub or RC phone, to appear in OnBot Java.
For all 3 methods, first connect the laptop to the internet, and open this link in a new Chrome browser tab: [Datalogger.java](https://github.com/FIRST-Tech-Challenge/WikiSupport/blob/master/SampleOpModes/Datalogging/Datalogger.java).
**Method 1**
<br>Click the `Raw` button at the right side, to open a page with raw text. Right-click anywhere and choose "Save as...". Change the "Save as type" from "Text Document" to "All Files". Navigate to the laptop's Downloads folder, then click the `Save` button.
- Next, do the same steps for this file [ConceptDatalogger.java](https://github.com/FIRST-Tech-Challenge/WikiSupport/blob/master/SampleOpModes/Datalogging/ConceptDatalogger.java).
- Now connect the laptop to the robot via Wi-Fi, as usual. In the Chrome browser, open OnBot Java. Click the Upload Files icon (green circle, below), to upload both Java files to the OBJ 'teamcode' folder (yellow oval, below).
**Method 2**
<br>Click the icon for "Copy raw contents", located to the right of `Raw` and `Blame`. In a plain text editor (a good choice is [Notepad++](https://notepad-plus-plus.org/downloads/)), open a New file. Paste the clipboard's stored code into that file, and save as **Datalogger.java** in the laptop's Downloads folder.
- Next, do the same steps for this file [ConceptDatalogger.java](https://github.com/FIRST-Tech-Challenge/WikiSupport/blob/master/SampleOpModes/Datalogging/ConceptDatalogger.java); save as ConceptDatalogger.java.
- Now connect the laptop to the robot via Wi-Fi, as usual. In the Chrome browser, open OnBot Java. Click the Upload Files icon (green circle, below), to upload both Java files to the OBJ 'teamcode' folder (yellow oval, below).
**Method 3**
<br>Click the icon for "Copy raw contents", located to the right of `Raw` and `Blame`. Now connect the laptop to the robot via Wi-Fi, as usual. In the Chrome browser, open OnBot Java. Click the large plus-sign to create a new file named **Datalogger.java**. Empty/delete all its contents, then right-click and Paste the clipboard's stored code into that file.
- Next, connect the laptop again to the internet. Do the same steps for this file [ConceptDatalogger.java](https://github.com/FIRST-Tech-Challenge/WikiSupport/blob/master/SampleOpModes/Datalogging/ConceptDatalogger.java); name the new OBJ file ConceptDatalogger.java.
<br>
<p align="center">[[/images/Datalogging-1/020-upload-circles.png|020-upload-circles]]
<p><br>
After completing one of the above methods, both files appear in OnBot Java and are stored on the RC device (Control Hub or RC phone).
If using an Expansion Hub with RC phone, change Line 40 in ConceptDatalogging.java from "Control Hub" to "Expansion Hub 1" (or other configured name for that Hub).
Click the wrench icon "Build Everything", wait for the message "Build Successful". Now the **compiled** versions of these files are also stored on the RC device.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Run OpMode and Collect Data
1. On the Driver Station (DS), select the TeleOp OpMode listed as "Concept Datalogger v01".
2. With the Hub at rest, touch INIT on the DS screen.
3. When ready, touch the START arrow, then begin physically moving the Hub by hand.
- Without disturbing its power or USB connections, carefully rotate the Hub clockwise or counter-clockwise, and tilt the Hub left-to-right, and top-to-bottom.
- If your Hub is mounted on a complete robot, carefully rotate and tilt the entire robot.
- Observe the live telemetry of IMU rotation angles on the DS screen. Do this for 5-10 seconds, then touch the STOP square on the DS screen.
4. Data collection is done! Click the Chrome browser's Refresh icon (curved arrow) to see the new log file listed in OnBot Java at the left side. The file "datalog_01.txt" is now stored in the RC device folder FIRST/java/src/Datalogs.
5. Optional to click the name "datalog_01.txt" to examine its contents in OnBot Java. The format is 'comma-separated values' or CSV, with headings in Row 1, followed by data rows.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Transfer Datalog to Laptop
Right-click on "datalog_01.txt" and choose Download -- then **pause** to read the next step.
During the download dialog, **change the file extension from `.txt` to `.csv`**. (If needed, change the "Save as type" from "Text Document" to "All Files".) This change allows the file to be automatically recognized and imported by spreadsheet programs. Navigate to the target folder on the laptop, and click "Save".
<!-- Note to self: in SDK 7.1 OBJ does not allow Rename from .txt to .csv -->
<br>
<p align="center">[[/images/Datalogging-1/030-download-circles.png|030-download-circles]]
The downloaded CSV filename may appear at the bottom of the browser window.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Charting with Excel
On the laptop, double-click the CSV filename to automatically open it in the **default spreadsheet program** such as Microsoft Excel (if installed). Or, right-click and choose "Open with...", then choose Excel.
<i>If you will do charting on a separate computer, first transfer the "datalog_01.csv" file from the laptop to that computer.</i>
The file will open in Excel, showing the 7 columns and many rows of data. Click on any **column heading** (the letter, not the label) to select its data for charting. While pressing `SHIFT`, click to select a range of columns (e.g. D - E - F). While pressing `CTRL`, click to select multiple single columns (e.g. D and F).
<br>
<p align="center">[[/images/Datalogging-1/040-Excel-1-circles.png|040-Excel-1-circles]]
Click the top menu item "Insert", circled above in yellow. Then click on the icon for charts (see green arrow). Then click the basic 2-D Line style, circled in blue.
This will insert a simple line graph of the selected data, as shown below.
<br>
<p align="center">[[/images/Datalogging-1/050-Excel-2-circle.png|050-Excel-2-circle]]
That's it! You have successfully stored and charted data from an FTC robot.
- If you "Save As..." Excel format, your original CSV file will not be affected.
- Excel locks any open file. After charting and review, close Excel or the open CSV file as needed.
Excel offers many more data evaluation features, beyond the scope of this tutorial. You are encouraged to learn and explore those features, ultimately providing a better understanding of robot performance. This may help you with troubleshooting, optimization and robot design.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Charting with Google Sheets
Connect the laptop to the internet. In a new Chrome browser tab, type "sheets.google.com". Then click the large plus sign in the lower right corner, as shown below.
<br>
<p align="center">[[/images/Datalogging-1/060-Sheets-01-marked.png|060-Sheets-01-marked]]
<br>
<p>
This creates and opens a new untitled spreadsheet. As shown below in yellow, click "File", then "Import". Then click "Upload".
<br>
<p align="center">[[/images/Datalogging-1/070-Sheets-02-marked.png|070-Sheets-02-marked]]
Drag the "datalog_01.csv" file from Windows Explorer to the rectangle shown, or click the blue "Select a file..." box to manually find and select the CSV data file.
For this example, the default settings are good, as shown by the yellow check-marks below. Click "Import data".
<br>
<p align="center">[[/images/Datalogging-1/080-Sheets-03-marked.png|080-Sheets-03-marked]]
The file will open in Sheets, showing the 7 columns and many rows of data. Click on any **column heading** (the letter, not the label) to select its data for charting. While pressing `SHIFT`, click to select a range of columns (e.g. D - E - F). While pressing `CTRL`, click to select multiple single columns (e.g. D and F).
As shown below, click "Insert", then "Chart". This will insert a simple line graph of the selected data, as shown below.
<br>
<p align="center">[[/images/Datalogging-1/090-Sheets-04-marked.png|090-Sheets-04-marked]]
That's it! You have successfully stored and charted data from an FTC robot.
At top left, type a filename to replace "Untitled spreadsheet". There's no "save" button; Sheets changes are automatically saved online.
Google Sheets offers many more data evaluation features, beyond the scope of this tutorial. You are encouraged to learn and explore those features, ultimately providing a better understanding of robot performance. This may help you with troubleshooting, optimization and robot design.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Run It Again
You will generally create **multiple datalogs**, which need different filenames. Here are two ways.
- **Recommended** In OnBot Java, click on "ConceptDatalogger.java" to view its Java code. At line 43, change "datalog_01" to "datalog_02". Then click the wrench icon "Build Everything", wait for the message "Build Successful".
- **Alternate** In OnBot Java, always Rename the latest datalog file. For example, right-click and Rename "datalog_01.txt" to "IMU angles - run 01.txt". After the next run, you will Rename "datalog_01.txt" to "IMU angles - run 02.txt".
Now re-run the OpMode:
- On the Driver Station, select the OpMode again, still listed as "Concept Datalogger v01".
- With the Hub at rest, touch INIT.
<!-- Hidden note: the SDK now completes imu.initialize() before continuing to the next command. No pause is needed. -->
- When ready, touch Start.
- Manually move the Hub (or full robot) for 5-10 seconds, then touch Stop.
Now download and chart the new datalog:
- Refresh the Chrome browser
- Download the datalog, **changing the file extension from `.txt` to `.csv`**.
-Open the datalog in Excel or Sheets
- Click the column headings, Insert a line graph
Now you have another set of charted robot data. Save and name the spreadsheet.
**Repeat this a few times**, until the process seems familiar. This will help with the next stage, customizing the OpMode to log your own data.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Other Data Sources
The sample OpMode logged data from other sources besides the IMU. Column B shows a **text code** based on user action, Column C shows a **loop count** generated by the running OpMode, and Column G shows **battery voltage** from the REV Hub.
For this data, you can experiment with other charting and reporting tools in your spreadsheet software (e.g. Microsoft Excel or Google Sheets). These alternate display methods are also considered Datalogging.
The next tutorial in this series shows how to collect data from motors, servos and sensors.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Summary
<!-- Video: Datalogging demonstration on YouTube -->
Teams using OnBot Java can use Datalogging to investigate problems and improve robot performance. Android Studio programmers can use all the same Java code described above. MyBlocks created in OnBot Java can make Datalogging available to teams using FTC Blocks.
FTC students will benefit from this valuable skill, widely used in professional fields such as engineering, scientific research, medicine, social media and marketing, business management, and many more.
You are encouraged to submit and describe other examples that worked for you.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
========
This is **Part 1** of a 4-part series on FTC Datalogging.
[**Part 2**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging,-Part-2-Custom-Data) shows how to customize the sample OpMode to log other robot data of your choice.
[**Part 3**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging,-Part-3-RC-File-Transfer) shows Android Studio users how to transfer datalog files from the RC device to a computer. (This isn't needed with OnBot Java, where datalogs appear on-screen for easy Download.)
[**Part 4**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Datalogging,-Part-4-Java-Learning-Exercise) describes the inner workings of a **different**, much simpler Datalogging class. It's strictly a Java learning exercise, showing basic steps to log robot data on the RC device. It does not require familiarity with Parts 1 and 2.
***
<i>Questions, comments and corrections to westsiderobotics@verizon.net</i>