New Programming Manual
 

Hi Everyone!
I am creating a programming manual/tutorial/ how-to book for people getting started in Java.

I want to make sure that I am including all of the important points and references.
So far, I have
- link to FIRST's instructions on how to download NetBeans
-How to open and download Default code
-Set IP Address and reimage
-download your code
-Creating your own Drive code (This section needs work. I bring up all the premade functions, but am working on how to describe other possible drivetrains)
-Basic custom control (Joystick to motor. -- might end up including Joystick to servo)
-Set up your radio/wireless system
-inverting a motor
-Basic vocabulary (syntax, servo... Things that a rookie might not know)
-How to set up your own motors,sensors, and other objects. Along with Variables and constants

Is there anything more that people want to see? (I have more sections that I plan to add, but these are the ones I am working on or have finished)

Eventually, I plan to post the completed thing here and on our website (It's not on this computer.)

Re: New Programming Manual
 

Think about posting draft versions of each section as you go along; we'll critique it for you, no charge.

Let me start out by saying that I know almost nothing about programming an FRC robot. And even less about Java.

The section on hardware- driver station, wireless, IP, and such should also include a troubleshooting guide, what are common problems one might see and where can I start looking. Include info on what to do when the router (for example) is totally farkled. Also, links to detailed info about the item, such as voltage and other specs (owners manuals?)

Consider the real beginner who might have nothing but your guide. Spend 3 or 4 pages on a step by step going from nothing to installing some code (supplied) that will at least make one motor respond to a joystick. And a basic wiring diagram (or link to one) so the programmer has some basis in reality.

How to read a digital input (and a sample circuit), how to set a digital output, how to read an analog input (and a sample circuit - use a potentiometer). Knowing that, I can read any sensor on the planet.

Last but not least, a half page on good programming practice: Commenting code as you write it, compartmentalizing/modularizing code, etc.

Re: New Programming Manual
 

So here it is so far. It still need a lot of help with wording, and I am concerned that I don't have all the major points. Please comment on anything you think would be good to include, change or take out!

The last section is only half done, and I think if I rearranged the Sections, it would make more sense. (But I don't know what order would make the most sense. - Help please?)

Re: New Programming Manual
 

Has anyone worked out Version Control on Netbeans? I know its built-in, but I didn't quite figure it out, instead I just made a new project....

Re: New Programming Manual
 

I've just begun adding section on how to read a sensor to control a motor (analog or digital and on the driverstation or off of it)
Sensors included are limit switches, potentiometers, general analog, analog sensor on DS, and buttons on the DS. Is there anything else I should include?

It includes code. I haven't worked with an accelerometer myself, so I don't know when or how you would use it. How it is normally used?

Re: New Programming Manual
 

There are three "common" uses for accelerometers that I know of:

1. Setting an "acceleration threshold" and getting alerted when the vehicle experiences a sudden acceleration greater than this. This is how they are used for deploying airbags, for example.

2. With a 3-axis accelerometer that is stationary, you can determine the direction of gravity. Accelerometers measure acceleration relative to a free fall, so on a stationary platform, you will always read a total acceleration of +1G upwards (the normal force of the ground pushing back on you). If the Z axis is the up-down axis, then when your accelerometer is flat on the ground you expect to read +1G on the Z accelerometer, and 0G on the X and Y accelerometers. But if you are pitched 45 degrees into the X axis, you would instead expect to read +sqrt(2) G in both the X and Z axes, and 0G in Y.

3. By integrating the output of an accelerometer, you obtain a speed estimate (since acceleration is the time derivative of velocity). If you integrate it again, you obtain position (since velocity is the time derivative of position). So accelerometers can be used (typically along with gyros, magnetometers, and/or compasses for angular measurements) as part of an IMU, or inertial measurement unit. However, these systems tend to drift over time - if your acceleration measurement is noisy at all, the noise will be compounded over time by your (double) integration.

Re: New Programming Manual
 

It seems to me that an accelerometer wouldn't be a common sensor for a beginner programmer to use.
- That said, does anyone have an excerpt of code I could use?

And here is a more recent copy of the manual. (accelerometer section is blank. Working on a good way to explain it. I think I might use Jared's explanation)

Re: New Programming Manual
 

Sorry. I didn't realize that moving the document from word 2007 to 2003 compatable would make the page numbers be all funky. I've fixed it for the next version, but I am going to wait until I have a few more changes before post the new one.

Re: New Programming Manual
 

I realized I forgot to add encoders on the sensor list. They are now included!

Re: New Programming Manual
 

I know this is a nerd turf war thing (http://xkcd.com/743), but can you please use a more open document format? It is about 1.5 times faster for Word to read OpenDocument Text than its own format (ROFL).

And I use OO.O, and disabled m$ compatibility.

Re: New Programming Manual
 

Here's the newest version - I've started adding in pictures.

Note: I will move the Tabbing section. I just wrote it, so right now it is at the bottom. It will soon be higher up.

I'm still looking for accelerometer code - If you have it in C++, I can just do the small changes to make it into Java.

If you have anything you'd like to see added or clarified, please PLEASE tell me!

Re: New Programming Manual
 

How do you convert it from a Word doc to OpenDocument? I didn't see how.
I can easily convert it to a pdf if that would work for you. - Why would you disable ms compatablity? A lot of places send their stuff in MS office formats.

Re: New Programming Manual
 

I don't recommend printing it out yet, I thought that the page references would automatically update, but turns out that they don't, they still link to the right spots in the text, but the numbers themselves are wrong. That'll be difficult to fix, but it should be good (mostly) by the next version.

Re: New Programming Manual
 

hit ctrl-shirt-s, choose odt

Re: New Programming Manual
 

You seem to be using an older version of Word (hence the .Doc and not .Docx format). Word 2003 and prior doesnt convert to OpenDoc format. I'd suggest you not convert to openDoc anyways as the formatting can become Borked, and instead convert it to a .PDF (use CutePDF writer, it's free and works great ... to the PC it's just another printer) and post it in that format since most can get an acrobat reader free, if they don't alreadyt have it.

Re: New Programming Manual
 

I'm using Word 2007, but Delphi doesn't accept the .docx file extension.
I'll post it in a pdf once I finish making some corrections I caught. (maybe 20 minutes?)

Re: New Programming Manual
 

So I explained a couple of things better, changed to a table of contents and fixed the tabbing and colors that got messed up.

I've included both a .pdf and .doc version of the manual. They *should* be the same....

Re: New Programming Manual
 

There were a couple "reference cannot be found." I fixed that (I hope) and added in a section on Versioning.

Re: New Programming Manual
 

if you are using word 07, please use ODT. Some people disable .doc file parsing to save about 30 MB of memory per session (on average).

Re: New Programming Manual
 

I've rearranged some of the sections, and added one on a Timeline and another on Competition tidbits.

EDIT: I still haven't been able to find the option to save as ODT. I hope that everyone can at least read the pdf.

Re: New Programming Manual
 

I've added definitions of Autonomus and Operator Control.

PLEASE COMMENT ON ANYTHING! I really would love feedback!

EDIT: this one doesn't have the updated table of contents. See the next post for the one with updated Table of Contents.

Re: New Programming Manual
 

Sorry, I forgot to update the table of Contents. Here it is with the updated table of contents.

Re: New Programming Manual
 

Just so everyone knows, this manual will be going up on 2234's website (www.episcopalacademy.org/robotics) over the summer. We about to remake the entire school website, so this will be added in the revision.

Re: New Programming Manual
 

Some small stuff managed to slip through my fingers, those have been edited....

Re: New Programming Manual
 

I just took a read through your latest version - this is a very useful document so far! What is perhaps most useful is that it is being written from the point of view of a student who has learned in a hands-on way, rather than by a professional programmer. The different perspective will definitely help it to be more accessible to many.

Keep it up!

Re: New Programming Manual
 

Thanks Jared!

Re: New Programming Manual
 

Hey a heads up:
http://livemyst.comli.com/wpilibj/doc/index.html
==> We need a new host for the javadocs, these are actually *prerelease* documents that are now way out of date. Sure for 95% of things people will be fine, but this is suboptimal still. Can you point users in the direction of local copies of the javadocs for squawk & wpilib? they are in the sdk folders.

Re: New Programming Manual
 

Versioning:
Our team used
projectname-yyyy.MM.dd.hh.mm (description)
The autosorting still keeps them in the right order, you get a summery of the changes, and can have multiple projects in the same directory.
Also, if we are working in the same directory as the backups, we use the version `wch' to mean the working copy. This still works, since `w' will autosort to after anything you would put in for yyyy, so it is ``more recent'' than any of your backups.

Of course, we didn't use that much this year, since we used an actual versioning system. We use Mercurial, since it seamed easiest to set up on Windows. You will need to install it separately from here (if you're using a package manager, use that instead). I've already made a post on Mercurial (http://www.chiefdelphi.com/forums/sh...d.php?t=83588).
I later realized, that even though Netbeans makes you do this, Mercurial normalizes all newlines in the archive anyway, and rejects the commit as an empty commit. Also, newer versions of Netbeans do not have this problem.

In order to clone between computers with Mercurial, you need SSH. Most of the time, we would just clone to a USB drive (using above naming convention for the clone). However, especially if several developers are working at the same time, cloning is very nice. Though it we never found a `great' solution, using Cygwin to install openSSH on Windows machines seems to be the best option. Don't use the stripped down ssh-only cygwin program.

Formatting:
Brackets
While I respect your code formatting choices, every programmer I have talked to generally agree that not giving braces their own line improves readability and economy of space
Although, many C programmers make an exception for functions, and give the brackets their own line. This is because it's what's in K&R C.

Tabs
Also, all of our programmers agree that it makes editing code way easier if you use tabs instead of multiple spaces. This can be adjusted in Netbeans by going to Tools/Options/Editor/Formatting. Uncheck ``Expand tabs to spaces'' and adjust the first to numbers to 4 (or, both to 8, if you prefer. I use 4 in OO languages, 8 otherwise).

Netbeans shortcuts
Also, it should probably be noted that in Netbeans, if you highlight several lines of code, you can hit <tab> to shift them to the right, and <shift>+<tab> to shift them to the left, instead of clicking the buttons.

Javadocs:
Instead of giving users a link to a web page with the WPILibJ javadocs, you should give them the location on their computer, since at competitions they probably won't have Internet, and it might change with an update.
on Windows:
%USER_ROOT%/sunspotfrcsdk/doc/javadoc/index.html
on *NIX:
$HOME/sunspotfrcsdk/doc/javadoc/index.html

Also, you should talk to them about writing javadocs for their own code, if you have a complex robot (or, at least complex code), this is a life-saver. It also makes it way easier for a new programmer to wrap his head around your code-base.

Misc:
Correction: You note that in the default code, they use `m_' for ``robot parts''. Actually they use it for anything that will likely be changed frequently (likely the `m' is for `mutable'). For example, the the active buffer in the network code in WPILibJ is m_buffer (or something like that).
Typo: in ``COOLEST THING I SAW'' (which is *very* cool), the sample code you give will not work, you use
when getting the different pots from the drive station.
Suggestion: It may be educational for programmers to peak at the WPILibJ source code. It is installed at `sunspotfrcsdk/lib/WPILibJ/' (same sunspotfrcsdk folder as the javadocs, see above)

Re: New Programming Manual
 

FYI--
is actually the prescribed formatting style laid out in the official conventions

Also,
I'm not sure I would point students in the direction of the WPILib src, just because its more of a port of a C++ library than a really well done java framework, and so isnt exactly a model for development.

Re: New Programming Manual
 

Indeed. However, there are a few items in that document that I strongly disagree with (mainly indentation, and secondly, commenting).

Even so, it is something that they will be interacting with regularly. At some point, to properly understand something you must ditch the documentation, and just look at what the code is doing.

Re: New Programming Manual
 

Hello,

I read through your guide and it seems very complete and useful. I did notice that your version control section was lacking. My team has successfully set up a subversion server that intergrates into Netbeans. If your still working on the document, I would love to help you complete that section.

Re: New Programming Manual
 

I've gotten git working as well (but not with NetBeans yet -- haven't tried). Might be useful for the *nix guys out there.

Re: New Programming Manual
 

Well, still haven't seen the thread owner post back, but I'm going to try to write out a quick description of what our team did to set up the server for Netbeans in order to help all those teams out there the would like the info.

First, one needs to get a server. This can be done in two ways. One, use a free public hosting server service, like google code. Two, start your own apache server (If you know how to do that, you really don't need to be reading this). Google code project hosting is simple to set up and was used by our team last year to host our svn server.

Two, one needs to set up integration with netbeans. Instruction here are for Netbeans 6.9.1: Select the desired project to be used with subversion as the main project. From the Team menu option -> Subversion -> Import into repository. A series of windows will pop up that will ask you for the URL of the repository, username and password. The repository URL can be found for google code under the source tab usually of the form: https://projectname.googlecode.com/svn/trunk. Users have to be registered with the project and the password is the google code generated password that is provided. That should finish up configuring the repository.

To check out from the repository, one need to navigate to Team->Subversion->Checkout. Enter the URL, username, and password that can be found from above and checkout the project. Svn commands can be found by using the team menu option or by right clicking on the project name (Commit, Update)

-Any questions, just ask

Re: New Programming Manual
 

Hi everyone!

I haven't checked Delphi in a while, I've been really busy with school and everything.

Because I posted both the pdf and the word, you should be able to edit it as you can come up with information/more clear explanations.

Brad Miller might be putting it up on the java section of First.wpi.edu
Unfortunately, I don't have any of the parts anymore because I'm at college, but anyone can update/test their ideas!

Re: New Programming Manual
 

You set up the links correctly, but MS Word doesn't update automatically. Highlight the text with the link (you can "Select All" for the whole document) and hit F9 to "update field codes". I tried it on my downloaded copy and it seems to work fine.