Architecture for software

[tubeheaD37]

Last year, as the only programmer on the team, and with only a limited knowledge of programming myself, our code turned out disgusting, disorganized, and generally, not pretty. Over the summer I did some learning, and now, its almost time again to attempt to program the robot.

In order to organize myself and the few other team members who are now willing to help me, I decided to create an architecture for the software so that there is a plan for every method and an overarching plan for what the software should look like in the end. Does anyone know of any similar projects which have been done before? Anyone have any good adivce for how to go about this?

[Alan Anderson]

When I came on board as the programming mentor for the TechnoKats in 2004, I didn't know anything about the IFI control system. I did have some clear ideas on software architecture, and they fortunately turned out to match the way things were set up in the system. I have three basic pieces of advice for everyone who starts with the default code.

First, make good use of abstractions. Don't write code that directly names joystick input pins and pwm output pins. Instead, use aliases like this:

#define OI_LeftDrive			p3_y
#define OI_RightDrive			p4_y
#define RC_DIG_Pressure			rc_dig_in09
#define RC_RLY_Compressor		relay6_fwd
#define RC_PWM_LeftFront_CIM		pwm09
#define RC_PWM_LeftRear_CIM		pwm10
#define RC_PWM_RightFront_CIM		pwm11
#define RC_PWM_RightRear_CIM		pwm12

Second, try to split the functions that read the operator inputs from the functions that set the motor and relay outputs, and try to keep both of them distinct from the functions that turn inputs into outputs. Put all your OI stuff in the equivalent of Default_Routine(), and keep track of what your operators are requesting in a global variable structure containing things like desired speed, desired turn rate, desired arm position, etc. Put all your motor control stuff in Process_Data_From_Local_IO(), basing the outputs on what's in that global variable structure. Put the code that decides how to change from what the robot is doing now to what it's supposed to do next in a separate function that manipulates the global structure based on robot sensors. It might seem inefficient to do it that way, but it permits a lot of flexibility, and the RC has plenty of power.

Finally, try to keep separate tasks in separate functions, but try to keep everything relating to a specific robot subsystem together. Our 2007 program has functions like Read_OI_Input() and Write_OI_Feedback() in the user_routines.c file, and process_feedback(), process_drivebase(), and process_arm() in user_routines_fast.c.

[EHaskins]

I had the exact same experiance my first year. I did have some knowlege of PC programming, but nothing like the RC.

I suggest you take your code from 07, and re-organize it so its logical. If you take your code, and look to see exactly where and how you went wrong, you will have a much better chance of avoiding those mistakes next time.

If you want a good book to read on the subject, I suggest Steve McConnell's Code Complete. It is aimed at professional PC programmers, but it has a lot of good advice.

[Robostang 548]

Our team created a patterns and practices document because we have a total of nine programmers this year. It drew out some simple and easy to follow guiedlines for commenting our code as well as the naming of variables constants, and alliases. While we try to create alot of pc programming projects (scouting software, etc) to keep our programmers busy durring the build season (to many people working with the RC just slows us down), the supreem law of the land on our team is that no programmer should have nothing to do because he/she can always doccument their code better.

-Don

[lukevanoort]

Diagramming is very handy too. Depending on how complex your code is, it may seem a waste of time; it's not, a good diagram can greatly increase programming efficiency. For example, the simplest diagram is just a block diagram that defines various 'blocks' of code and their interactions, and once you have a block-level diagram you can then set each programmer to develop a different 'block.' If the diagram is good enough, with defined interblock interfaces, all the programmers can be working on and completing code independent of each other.

There are many other types of diagrams, but I feel most are probably not worthwhile in our application. The only other one I can think of that is worthwhile is the 'Use Case Model'--essentially a stimulus-response chart. A use case diagram diagrams out how a program will respond to users inputs.

A decent, free program for diagramming is Dia. Check it out, it has more type of diagramming than a programming team could ever need. (unless you dabble in cybernetics, telephony, and hydraulics)

[Tom Bottiglieri]

Try to organize data in predefined structures and write generic functions that do work on those structures. That way if you would like to create a new instance of *something*, you can do it with limited headache. This worked well for us with things like PID control loops.

typedef struct{
  int	dState,      	// Last position input
	iState,      	// Integrator state
	iMax, 
	iMin,  	        // Maximum and minimum allowable integrator state

	iGain,    	// integral gain
        pGain,    	// proportional gain
        dGain;     	// derivative gain

  unsigned char mode1; //0 for position, 1 for velocity

} PID;

And then you can use the data like this

//Global
PID shoulder;
PID wrist;

//Function Call
void SetUpMotor(){
   InitPID(&shoulder,p,i,d,imin,imax);
   InitPID(&wrist,p2,i2,d2,imin2,imax2);
{
    
    
//Function Definition
void InitPID(PID *pid,int p, int i, int d, int i_min, int i_max)
{
    pid->pGain = p;
    pid->iGain = i;
    pid->dGain = d;
    pid->iMin=i_min;
    pid->iMax=i_max;
}

Notice how we created 2 separate PID loops with minimal code. This mimics object oriented languages like C++ or Java.
Be very careful with pointers. If you accidentally write over a reference and not a value, you will get undefined behavior out of your program (no compiler error or runtime error, just lots of weird stuff happening)