Rewrite of Getting Started section

[Daltz333]

It has come to attention that the getting started section needs many works done. This document will hopefully outline a couple of ideas and solutions.

• Rewrite to be more like a 0-to-Robot (hardware may be difficult)
• Focus on what people need
• The output should be a working driving robot using KOP

Break up content into it's specific sections. Perhaps address "what is X hardware" as we go?

Address the discontinuance to articles. This may need some breaking renames. This may be related to reorganizing WPILib Overview.

[Daltz333]

A couple of thoughts, version 1

I think we should split up setting up the robot, versus setting up tooling for software. This will probably be more clear.

What is the very first thing a programmer needs to get started (once the hardware is setup).

Step 1: Installing some dependencies

• WPILib
• National Instruments Driver Station
• Third Party Devices Installers (REV and CTRE)

Step 2: A (very brief) overview of the software tools

This will just introduce them, replacing the Control-System-Software page to an extent. This should flow seamlessly

• VSCode
• Driverstation
• Shuffleboard/Smartdashboard
• The other tools are secondary for getting started

Step 3: Launching VSCode and a brief overview of the UI

• Showing how to create a robot project
• Importing the vendor dependencies

Step 4: Programming and Deploying code

• An overview of the different programming modes (teleopPeriodic vs teleopInit vs autonomousInit, etc)
• Programming a DifferentialDrive robot to move (TimedBased vs Command-based?) using the XBoxController class

Step 5: Advanced (just slightly) Getting Started

• Going straight PID using a gyro
• Branching out into the more advanced topics that users may want (central collection of document links)

Additional Design Notes

• Programming and Electrical Basics should get renamed to "Robot Getting Started"
  • Each of the new articles should appear in the TOC under this.
• WPILib Programming Basics should get renamed to "Control System Basics"

The goal of this is to make the getting started overall more cohesive.

[Daltz333]

@Kevin-OConnor I would appreciate your thoughts on this. Hardware is a different beast to tackle, but I think keeping them separate but leading into each other would still be useful.

[bryanyli]

For a "Getting Started" section, I think TimedRobot is the better option due to rookie teams being more likely to use it. However, that could because there's no good "0-to-Robot" tutorials/guides for the new command-based framework, which could deter new teams from using it and deter teams using TimedRobot to switch to command-based.

Personally, I think that TimedRobot is primarily for two types of teams:

1. Teams that lack programming resources and experience and need to throw together a program with minimal knowledge (command-based requires OOP and knowledge of functional interfaces, we can't expect every team to have someone that has that knowledge)
2. Teams that use their own framework built off of TimedRobot

I think it's important to cater to the first category of teams, although I would love to see a "0-to-Robot" tutorial with the command-based framework in its own section.

[SamCarlberg]

TimedRobot is not for new and inexperienced programmers. The fundamental building blocks are there, but programmers have to be able to manage (and debug) their own state machines, while CommandBased provides that for free, as long as the programmer follows the framework.

RobotBuilder exists to make it easier for inexperienced programmers to write CommandBased programs by handling all the OOP concepts and letting the programmer only have to handle the specific logic of how some action should be done.

The old CommandBased system, while not as flexible as the new one, doesn't require needing to know how to use functional interfaces and lambdas (though conceptually, they're not too difficult to teach). I'm not sure where RobotBuilder currently stands on old vs. new CommandBased, though. I hope it supports generating code for both.

[ItayZiv]

I think that in general, it'd be better to cover command-based, it allows much cleaner code, more readable and that results in fewer issues, I think TimedRobot has so many more places to screw up. I'd say the basics of OOP aren't super hard to explain and is all that is needed for command-based. TimedRobot tends to get really messy unless the teams know what they're doing. I think right now, why a lot of more rookie teams use TimedRobot, is because of the lack of a full walkthrough, a full tutorial will probably allow teams to be able to effectively use it. I think TimedRobot also works, but I don't think its the most ideal if we're looking for a way to introduce teams to programming, especially since it will both be easier (imo) and allow them to do more in general in the future.

[Daltz333]

@ItayZiv I don't believe the purpose of the 0-to-robot is to teach programming as much as it is to get a functional robot

[sciencewhiz]

I'm not sure there's much correlation between team age and framework used

[ItayZiv]

Id say if you go 0-to-robot, and use a imo easier framework, and you can use that to be able to easily progress to better auto, its more beneficial to those teams. TimedRobot does require a lot of management with state machines and autos, binding buttons, how buttons are triggered etc etc...

[Daltz333]

To get a robot move in TimedBased

WPI_TalonSRX motorLeft = new WPI_TalonSRX(0);
WPI_TalonSRX motorRight = new WPI_TalonSRX(1);

XBoxController driverController = new XBoxController(0);

DifferentialDrive m_robotDrive = new DifferentialDrive(motorLeft, motorRight);

@Override
public void teleopPeriodic() {
  m_robotDrive.arcadeDrive(driverController.getY(Hand.kLeft), driverController.getX(Hand.kRight));
}

I would argue that this is less verbose than command-based.

[ItayZiv]

While the simple drive robot case is simpler, I think adding more conditions with Buttons and state machines for various actions are much easier in Command-Based, whole in TimesRobot these type of concepts would be very hard for most rookie teams.

[bryanyli]

Although it seems like it is easier to add functionality to Command-based robots after you get them set up (with RobotBuilder or manually), IMO it's harder:

See TimedRobot code for driving 3 seconds forward in auton:

private double startTimestamp;

@Override
public void autonomousInit() {
  startTimestamp = Timer.getFPGATimestamp();
}

@Override
public void autonomousPeriodic() {
  if (Timer.getFPGATimestamp < (startTimestamp + 3) {
    drive.tankDrive(0.5, 0.5);
  } else {
    drive.tankDrive(0, 0);
  }
}

compared to in command based after you have a subsystem set up:

public Command getAutonomousCommand() {
  return new InstantCommand(() -> drivetrain.tankDrive(0.5, 0.5), drivetrain)
      .withTimeout(3)
      .andThen(() -> drivetrain.tankDrive(0, 0), drivetrain);
}

The command based code requires new teams to have knowledge of command-based itself (race and sequential groups), as well as functional interfaces/lambdas. Even though these concepts could be taught, I don't think it belongs in a "getting started" section. The TimedRobot, on the contrary, only requires knowledge of the Timer class (and I think it could be made even simpler by using getMatchTime). Command based does provide a lot of convenience features for autons, but most teams with limited programming resources won't have the opportunity to use or benefit from most of them.

[ItayZiv]

You don't have to use inline and lambdas for autos, but I do think both auto and ever more than that the moment you need state machines to get buttons to work in a certain way. This is imo where command-based shines because it adds almost no complexity to stuff that manually managing in TimedRobot is very hard. On top of providing a much easier way for a team to progress, binding buttons in certain ways, and having a physical sequence (raising an arm and out taking, waiting to reach a position the doing X, PID even) is so much easier in Command-Based once you know the basics. If the only target is driving then TimedRobot is easier, but id say that's something quite limiting, compared to the flexibly of command-based once you learn it.

[bryanyli]

Even if you didn't have to use inline commands and lambdas for autons, you would still need knowledge of race and sequential groups, TimedCommand, and now at least basic OOP.

Handling inputs similar to command based's whilePressed is just a matter of an if statement. whenPressed is a bit trickier, but it can be done with an additional if statement and an extra variable.

I agree that command-based makes PID control or sequences of commands easier, as well as making it easier to deal with actions that run multiple subsystems/groups of actuators. My idea is a small "get a robot driving" with TimedRobot section in the "Getting Started" section, and then maybe a full "0-to-robot with multiple subsystems and auton" with command based in another section.

[sciencewhiz]

You don't even need a extra if statement and variable for detecting when a joystick button is pressed. https://first.wpi.edu/FRC/roborio/release/docs/java/edu/wpi/first/wpilibj/GenericHID.html#getRawButtonPressed(int)

[ItayZiv]

After further conversation, if the goal is just 0-to-driving, then I think TimedRobot is better, with an article/mention to command-based and explanation of why that might be useful/a tiny nudge towards that.

[flybotix]

I think the current mindset on approach (basic driving robot + PID control) works well for a coded robot guide. Yet there is one concept that should also be explained.

The concept that the entire robot is in a loop of discrete time is very hard to grasp for newcomers (they always ask where the for loop is...). The looping frameworks make this very verbose to deal with, whereas the command framework masks it*. So anything that can be produced to demonstrate this fundamental looping concept will go a long way to helping someone get started with robotics. It would also be language-independent and framework-neutral.

The debate on the different frameworks is a bit of a tangent for a "Getting Started Guide". One framework has a very deep, complex, involved API that must be learned before it's even useful (command framework) versus the others which have a much longer set of code to be written (everything else). It isn't intuitive on what needs to happen to get started with either framework unless someone has learned the framework already. The fundamental concepts are much easier to explain in Iterative/Timed, but that's usually because the concept and the framework goes hand-in-hand.

*Data issues tend to be the thing that new students to command framework struggle with, particularly when creating 'objects' that don't exist as part of WPILib already. Things like timed pneumatic actions, and XOR gate latches (useful for beam break sensor logic) seemed to be much easier to teach/debug in TimedRobot.

[Daltz333]

Remember that the key point for the getting started section is not to teach programming, it's to get a robot moving. That is the emphasis here.

[Kevin-OConnor]

There are a couple pieces we need to be mindful of here. We don't want to bury or remove the overview documents or LV documents (though it makes sense to me that we want to try to main a "click next" workflow for veteran teams on-boarding new programmers). The #1 piece of feedback we receive is "I wish there was a tool that" followed by a description of GRIP, Shuffleboard, Robot Builder, etc. And even if they just point to LV documents or tutorials all of the "control system" links FIRST provides point here so LV needs to remain approximately equally prominent as C++\Java from a beginner perspective.

I agree with sticking with TimedRobot for the getting started. I think providing at least some sense of what @flybotix is referencing in the description of the benchtop program makes sense. One of the most common errors we see is adding long running loops inside the robot code.

Maybe re-organizing things along this direction? (and potentially adding some of the additional content you have proposed into that last section?). This would let vet teams link their programmers to just the last section but still maintain a lot of the overview documents that I think are important for new teams that don't even know what any of the stuff is.

Overview
    Introduction
    FRC Software Component Overview
    FRC Control System Hardware Overview
    Offline Installation Preparation

Getting Started with Robot Hardware Installing the FRC Game Tools How to Wire an FRC Robot Imaging your roboRIO Programming your Radio Updating and Configuring Pneumatics Control Module and Power Distribution Panel

Intro to robot programming with LabVIEW Installing LabVIEW for FRC (LabVIEW only) Creating your Benchtop Test Program (LabVIEW) Running your Benchtop Test Program (LabVIEW)

Intro to robot programming with C++\Java WPILib Installation Guide Creating your Benchtop Test Program (C++/Java) Running your Benchtop Test Program (C++/Java)

[Daltz333]

@Kevin-OConnor So is your idea to structure things into an Overview, which lists the control system basics of things that are language agnostic. And then split up out things from WPILib and NI?

I'll reorganize the initial idea into this then.

[Daltz333]

Also, I think due to the new structure, a software overview is not needed due to the clarity of the sidebar. Each tool is quite obvious, versus ScreenSteps where it was buried under a nest. I also think the Offline Installation Preparation can be rewritten to be less jumbly.

[flybotix]

@Daltz333 I agree that the initial emphasis with a programming Getting Started Guide should be on getting a robot moving. Yet I think it is easy to immediately follow it up with breaking down why the robot moves in concise laymen terms. It will take some explanations of physics (for 9th graders - keep that in mind) and code (discrete time looping construct, even for Command).

[Daltz333]

@flybotix think that might be a good continuation in a potential series that branches off the getting started. Similar to LimeLights research studies articles.

I do feel that getting started needs more than a reorganizing and a rewrite.

Things do not mesh, and viewers see links and articles thrown at them with no context to each other. The Java/C++ section is grossly outdated and needs to be updated to be a bit more modern.

[Starlight220]

Many of the articles need to be updated/rewritten. There is little to no doubt about that. About the "Getting Started" section, I think it should remain general/abstract, and a more "streamlined"/concrete version should be added separately as a tutorial, built similarly to the Trajectory Tutorial. This way teams that want to quickly build/code a robot can use the 0-Robot tutorial, and when there is need to focus on a more specific topic (this is much more relevant to non-low-level teams, unlike the 0-Robot) they can use an article that goes to the depth of the topic they need.

[Daltz333]

@Starlight220 I agree with you, but in the reverse. To branch out the generic stuff elsewhere, and the getting started section should become the 0-to-robot.

[Starlight220]

@Daltz333, I said that they should be kept separate. The exact layout is up to you. The current "Getting Started" section is extremely verbose, and much of that shouldn't be in a starting section. For starters (pun intended), is there a more "officially endorsed" dashboard? If so, the docs for the other dashboards can be split elsewhere. For that matter, the whole "FRC Software Component Overview" can be split elsewhere, with each tool explained where it's used (i.e. go over the Imaging Tool in the "Imaging your RIO" section). Much of the 0-2-Robot section should be separate for C++/Java vs LV. The "FRC Control System Hardware Overview" article should be split into more delving articles on each category, and not be in a "Getting Started" section.

Either way, many of these changes are getting off-topic for this issue. I'll open a new issue for general refactorings.

[calcmogul]

is there a more "officially endorsed" dashboard?

The short answer is that Shuffleboard is the officially recommended dashboard, but SmartDashboard still fills a niche that Shuffleboard cannot (SmartDashboard is lightweight).

The dashboard progression was SmartDashboard, JFX Dashboard, then Shuffleboard. Each was intended to completely replace the previous one, but that didn't end up happening. JFX is completely gone because no one could figure out how to build it. SmartDashboard is the simpler and less resource-hungry older sibling of Shuffleboard. Shuffleboard supports better plots and data recording, but we've heard reports of it eating all the user's RAM and using more CPU.

I'm of the opinion that we need a lightweight dashboard that supports only two things: autonomous selection via NetworkTables/SendableChooser, and a camera stream (MJPEG or h.264) via cscore. It would be much easier to maintain than what we currently have, and it would cover the main in-competition use cases without teams paying for what they don't need. (I'll get around to making one at some point... it's basically just plumbing a couple API calls together in pyqt5)

[Daltz333]

I will be moving forward with the draft that I have written. Alongside some additional comments I have received from Kevin.

[Daltz333]

Okay, given the merge of #861 which reorganizes Getting Started in to Zero to Robot. It should now be much easier to rewrite specific portions and sections to have easier reviews.

[jasondaming]

Are there still things left to be done on this issue?

[AustinShalit]

@Daltz333

[Daltz333]

Yes. I want the programming section to get rewritten first. Not sure if this will happen before 2021, but docs isn't on a feature hold during season like allwpilib is. (all missing features is inheritantly a bug 😜)