Why I should get an....

The Vertical Power project would have been perfect for three people. It could have been a challenge for two people. And, it has been nearly impossible for less than two. I am not going to sit here and bash my partner but the question he had in the presentation session today about us going first and clear indications he wanted to leave after that to go study for another exam was indicative of the kind of committment I've seen throughout this project. I'm going to lay out what we've accomplished and what part of that was mostly my doing and I will let you, as the professor, decide what should go at the end of the title to this post.

Our first task was to understand how the Revolution system by Vertical Power worked and how the Small Switch Panel (SP) would need to integrate into the larger product. I studied the market requirements and the Control Unit functional requirements documents and talked extensively with Kevin at the start of this project about how everything was supposed to work. I believe that through our discussions we uncovered some weaknesses in the existing requirements and I hope that part of the process was helpful to Kevin.

The next task was to develop very specific functional requirements for the SP and write our requirements document. We had several brainstorming sessions to develop our requirements and Kevin was extremely helpful. I wrote the entire functional requirements section of our document. David wrote the rest but it seemed like more of a cut and paste job from what Kevin already had. David's input for the functional requirements was limited and showed he didn't have a clear grasp of the SP or how it fit into the overall system or the level of detail we needed. I tried to get David more involved and believed having him write the testing portion of our document would give him the insight he needed to help design and implement our functional reqs. One additional part of this process was the development of the communication protocol with definitions for all the packets. I scrubbed the requirements for all components and helped give Kevin the basis for the much more extensive and organized Internal Communication Document he finalized. It was a bit of work but helped me understand the system better and hopefully helped Kevin.

Our next task was to develop the design for the SP software. Although it was not listed as a specific requirement, the design and implementation of a multi-threaded type non-blocking serial IO interface and associated network protocol was instrumental to the function of the system and clearly the most difficult part of our problem. Again, Kevin helped a lot and gave a lot of direction with the comm sections but, so far, I have written the entire design document with the exception of the EEPROM module. At first I only focussed on control flow and the serial IO and protocol modules. David was to fill in the switch, light sensor, magneto dial, EEPROM, startup and shutdown sections. We decided to postpone any work for the bootloader as a last priority. The functionality of the non communication components is pretty simple and we felt this was a fair distribution of the work. I ended up filling in the blanks for everything except EEPROM, startup, and shutdown in the documentation. It still needs work but I believe the document will be ready for tomorrow even if it's not everything I would have liked it to be. At Kevin's request and what ended up being very productive for us, David and I developed a module interraction diagram. We were farther along in the project at this point and we probably wouldn't have gotten it right without David and I working together. David drew up a UML diagram for what we came up with and should be putting it into our design document. To tell the truth, I haven't had time to even look at it yet and have been working off my notes for that session. David will also be putting the readme section into the design document for getting any newcomer to the project started up quickly and I will be adding sections to each module for current implementation and problem areas.

Our next task was coding and testing. Again, initially I was focussed on the communications and David was going to focus on the rest of the essential functionality. At this point I have coded everything we have except for the EEPROM files. David had a great idea to use interrupts to synchronize the flashing of all lights when they needed to be blinking but his implementation of the PWM and the interrupts had a few problems. His implementation was hard to understand so I also ended up writing simpler timer file code in order to see some functionality.

We ended up being very individual units in the implementation and testing phase of our project. David was heavily wrapped up in doing the EEPROM stuff. Consistently, throughout this project I tried to explain what it was we needed to do, how the communications would work and how the rest might work, give him big chunks of the responsibility for design and implementation and try not to own the entire thing. Like I said earlier, this project would have been a challenge for two full students and I have other classes myself in addition to being a 24/7 single dad raising two young children. But when time would pass and I would hear questions and comments that just floored me, and there wasn't any design or coding getting done on the rest of the project, someone had to get everything going. David has tested his EEPROM code on the SDK kit. He has done some integration with the overall system but I haven't seen any stubs to hardcode initialization info into the EEPROM and use it to populate the switches at startup and I don't believe he has tested it on the real SP yet. The rest of what we have is basically my doing. I'm not proud of it at this point but testing and debugging has shown steady progress toward a completely functioning system.

I know it doesn't matter for the grade and there may be some doubts as to my commitment but I will see this project through. I've come tantalizingly close to seeing the functional requirements we layed out several months ago become a reality in the limited but very challenging and interesting world of microcontrollers. When I see a switch get flipped, the light go on, the new status properly communicated to the control unit, and the proper responses happening as a result of received messages I will be happy. When I reflect that we did it all on a microcontroller I knew absolutely nothing about 3 months ago I will also be proud.

I want to thank you for the opportunity to participate in a real project with a real company. It is an experience I think every student should have and I wish you all the luck in growing this class into the vision you have for it.

Thanks Again,
Marty Ridens

Our Demo

Well, demo night at Vertical Power was a bust. On Monday 12/11/06 at 7:00pm we hit the class deadline for showing functionality of the Small Switch Panel to Kevin. We will continue work on this project over the break but that isn't relevant at this point and for our class purpose.

We were doing well by Monday afternoon. There were issues with the communication system but we had reasonable functionality. We were sending and responding to messages and could show nearly all of the priority 1 items were met. We had most of the priority 2 ready to test and had seen succesful responses to several of these already. This still would put us well behind our original and even our revised schedules but at least we could show that some of what we did worked.

Alas, and I should know this, I did not commit the semi-working version to SourceSafe. While attempting to resolve comm issues I ended up breaking the communication software. When it was time to demo for Kevin, instead of sending a single message the SP would send many repeats of the same message, any responses were very sluggish if they occurred at all, and basically... we bit the dust. We weren't able to demonstrate even the most basic functionality. In another world I would have been up all night working with the system to get functionality back but we had missed our deadline and I had kids that needed to be put to bed. The looming and unshakable deadline of having quality documentation to submit for our class grade also took over and we had to bite the bullet and take whatever grade our work will earn us.

I am not a quitter. The final deadline for Vertical Power to have a fully tested and robust SP system is mid January and I am looking forward to solving the challenges remaining before us.

Design/Code/Test iterations

This has truly been a great learning experience. Not only have I received a great refresher course in C and developed a pretty good understanding of microcontrollers, but the insights into the software development process this project has provided are phenomenal. I am constantly revising the design document as new challenges and unforeseen issues arise. Our document is not in the shape it should be yet because it is missing several key components like the "readme" to indoctrinate newcomers and provide a high level view of the project. I feel the highest priority is getting Kevin some decent code which will hopefully work, is very well documented so that Doxygen can generate a great API for it, and has a solid basis in the design document. I have only concentrated on the design aspects of our document so far and all my code is heavily documented now following Kevin's coding conventions and Doxygen formats.

The Doxygen output will largely be a duplication of the design document so I don't think including it would be a good idea. I would like to submit the code I've written for some small part of my grade though. My plan is to finish coding over the next week and then spend time with the real board at Vertical Power testing while using the evening and night hours to refine our documents to include some of the nicer tidbits which should be part of a comprehensive document.

I must admit there were two or three weeks where I had pressing issues with my children and my custody battle to attend to and I only put 5-10 hours in. I felt bad about those weeks since this project was so immense (considering all that had to be learned and done). The rest of the time I have been committing at least 15 and usually 20+ hours to getting this thing done and I'm finally beginning to see the benefits of all I've learned. I'm also starting to feel a little proud of what we've done. Kevin's faith will not be totally misplaced, and that's another good thing.

Big Dump

Well, the coding has been going well... it's the testing that really bites. I believe the code for the serial io and protocol modules is very solid. Extensive debugging last week and over the weekend uncovered several problems with my original code. Part of the problem is my unfamiliarity with C but that is diminishing as each session progresses. I still do not have basic functionality though. David has helped with a few things like extern declarations to help clear up my code. I really need to go over it with Kevin though and he was tied up through all the time and testing we did down at Vertical Power Wed, Fri, and Sat. I just thought of a new test method though. I can leave the line from the PC to the serial port we use for downloading code to the microcontroller hooked up instead of trying to send messages from one MC port to the other. I ought to be able to open up a hyperterm and then see if I'm at least sending anything.

Frustration with my lingering io/network bug and our rapidly approaching deadline has produced some benefit though. Tonight I coded up the Light Sensor and Magneto Switch modules so we at least have the code for those. Testing is always the bugger though. The bright spot is this stuff is much, MUCH simpler and really should work with very limited debugging. The Switch Module behavior is smilar but slightly more complicated so we should be able to kill it tomorrow and meet most of our prority 1 deadlines... at least coded. It's going to be hard to test any of this stuff without a functioning network.

David has been working on the EEPROM and reset modules and he took the SDK home to work on for Saturday night and Sunday. Hopefully, he made some good progress. If his stuff is solid then all we'll need after getting the switch module coded is shutdown and boot loader. Oh, except that dang function table to respond to incoming messages. I'll need help from Kevin with that too but I'm finally thinking we might be able to actually pull this thing off in the next two weeks. And that is a very good thing.

Trouble with C

Getting back to programming with C is tougher than I thought it would be. Now, Im the one who will be dragging the project down. Ive found a few good references and am climbing a steep learning curve yet again on this project.

Atman kicks!!

The IDE Kevin has requested we use, Atman, is fantastic. Got it upand running over the weekend and began coding for the project. Atman takes care of setting up the framework for the code and handles initialization of the USARTs, IO ports, PWM, timers, and ADC with a very easy to use and understand interface. The code for the IO and protocol modules is not working yet but that is more a result of how long its been since I've used C than anything else. My plan is to have those modules working and sent to Kevin by our meeting on Thursday so I can help David get the rest of everything else running.

Meeting 11-07-06

Kevin and I both have some concerns over David's commitment and willingness to take on the level of work required for this project.

To date, I feel I have done an overwhelming amount of the work we have accomplished. I wouldn't mind so much if I was beginning to get a feeling he has worked to understand the Revolution system, the Atmel MEGA1280, our requirements, or the software design. It often appears he hasn't even learned enough to ask the right questions and seems to want to minimize everything from the requirements to the design. "Let's just do it, it's so easy" is a sentiment I feel he has conveyed but then he doesn't show a clear enough undertsanding to just do it.

Maybe I have been more dominant and not as much of a team player as I should. I know I have tried to communicate the importance of studying and understanding the documentation we have available. I have tried to work over the functional and design requirements but then I'll get a comment or question which makes me wonder if he's done much reading at all.

Today, Kevin and I decided that I should talk to him. We expected meat on the bones of the design I provided for handling changes to the switches and sensors. This is really a pretty easy thing to do, especially since I had provided control flow and several algorithms, but again we don't have what we need. Kevin is preventing us from writing code until he is confident we understand enough to move forward. This can only be displayed through clear and concise design work. I will talk with David and work with him on Thursday. I will be direct on asking him if he has any questions and trying to ascertain how much he really understands. I'll lay out the expectations clearly. I think Kevin has done a pretty good job of this already but we want to make sure we haven't failed in our communications.

On Friday, 11-10-06, we need to have a solid design for the complete system. I've taken on the hardest part of the project in designing the serial IO and protocol modules. We are basically ready to go there. I understand the registers and bits that need to be manipulated to make the microcontroller do what I need it to do. There is a big learning curve here since there are many details hidden in the datasheet for control register requirements. The code needs to be written in a certain way and all bits must be at their proper setting to enable the microcontroller to perform as expected. It isn't as simple as just writing code. Kevin and I both hope we will see David step up to the plate.

Overall Comments

This project is much larger than it might appear. To begin with, we are dealing with a microcontroller instead of a full system. This is a totally foreign environment to many CS, and apparently CE, undergrads so the first hurdle is to understand the microcontroller, the different approaches to design and coding required, and what tools are available.

The second issue is our integration to a much larger project. We are developing software to control the Small Switch Panel component of the Revolution system. The other, and much larger, systems are the Control Unit and the Display Unit. In order to understand how our component integrates with the others we need to understand the requirements of the other components. A second version of the system does not include the Display Unit but has an expanded switch panel called the Large Switch Panel. We are not writing the code for the large switch panel but our code will be used as a basis for the later development of that component. We must always be aware of the overall system requirements and make sure we don't do anything that will restrict the later development required.

The third issue is the tools we will need to utilize. The Atmel microcontrollers can use several different cross-platform compilers and IDEs for software development. All of these were foreign to us at the onset of this project. Kevin has defined the Coding Conventions so we also need to become familiar with those. Kevin has also required we use Doxygen for our comments and eventual documentation and manuals. While Doxygen may be easy to jump in to there is still a big learning curve if we want to utilize it to the best of its capabilities.

There is a huge amount to do and every day must be used wisely.

The Design Document

All through the requirements elicitation process I was mulling design ideas over in my head. I have scoured through the requirements for the other components of the Revolution system to understand exactly what our component needs to do and how it will integrate with the other components. I have also read most of the Atmel MEGA1280 microcontroller datasheet to understand the limitations and requirements of the environment we need to work in.

A few weeks ago I created a hand written version of the Control Flow required for the software running the small switch panel. I identified the needed functionality to meet our requirements and developed a few algorithms to handle the difficulties we faced working in a microcontroller environment, especially regarding timing and making sure we can blink lights at the correct rate and ensure a change has really occurred to any of the switches or sensors before responding to them. I developed a timing mechanism we can utilize for the entire system to handle all of our timing requirements and also developed the basic outline for handling all of the switch and sensor changes we need to respond to. I developed the data structures required for overall system functionality but admit these still need some refinement.

The most difficult part of this design is dealing with the limitations of the serial communication we have available in the Atmel MEGA1280 microcontroller. The serial port and USART only transmit or receive one character at a time. Kevin made it clear that all communications need to be non-blocking. It took me a little while but with Kevin's prodding and advice, research of other solutions that have been developed, studying the 1280 datasheet, and sheer determination I developed the design for the serial communication layer and the protocol layer of our network communications.

Last week, in order to make sure we had discussion material for our meeting with Kevin, I wrote the entire design document we have to date. It included Serial IO, Protocol, Main Loop, Switch, Light Sensor, Magneto Switch, and Reset modules. Last Friday I was aware, and Kevin reinforced that just thowing everything we needed down on paper was not enough and thr document needed refinement, the design needed better flexibility and detail, and we needed to be done by our meeting today.

David and I agreed that I would continue to work on the Serial IO and Protocol modules and he could take what I have developed (basic design and control flow) for the other components and refine the design.

Today, the Serial IO and Protocol modules are basically done. I have two minor changes to implement in the design and will have these done tomorrow. I will begin coding these modules and be ready to make sure everything else gets done so Vertical Power will meet its deadlines.

The ICD Document

The ICD is the Internal Communication Document. It contains the guidelines for network communications between the various components of the Revolution product. Kevin asked us to help him out with completing this document. Kevin had the format of a network packet defined and several of the command packets defined also. I scrubbed our requirements doc and the requirements docs Kevin had for the other components to develop a complete list of the communications required for the Revolution system.

My discussions with Kevin during this process refined our concept of how the network would need to behave and developed additional requirements.

Kevin provided the details for the kind of information I had identified we needed to transmit and I edited the final draft to incorporate his suggestions and details.

The Requirements Document

The requirement elicitation process and the creation of our requirements document was somewhat of a team effort. David and I did hold brainstorming sessions down at Vertical Power, but he didn't quite grasp the level of detail we needed for the functional requirements and didn't seem to have studied the documents Kevin provided (marketing reqs and the CU functional reqs) enough to have a clear understandingof exactly what we needed to do. I developed probably 95% of the functional requirements and did all of the write up for that section of the document. David did contribute by creating the rest of the requirements document but I think we could have done a much better job following the examples in the book and the Volere template rather than the bare bones Vertical Power version we did use as a guideline.

In an attempt to try and get David more familiar with the functional reqs we would need to implement I suggested he develop the test procedures and requirements to prove out each of our functional requirements. He took on the assignment but both Kevin and I feel that portion of our project needs a bit more work.

Rationale Notes

I will use this post to organize and record the thoughts and rationale for development and design decisions made during the software development for the Small Switch Panel portion of Vertical Power's Revolution product.

Journal Assignment #3 - Plan and Process

David and I have a different situation than most groups. We are part of a larger software development process which already has deadlines defined. Our motivation does not have to come from ourselves. We are driven by a desire to satisfy our customer (Vertical Power) and ensure that we are not the weak link in the chain. The company we are working for has real potential to make money and several people have devoted this portion of their professional lives to see their product come to fruition. When a student works on a project for a grade it is easy to make decisions to weaken the software development process, let deadlines slip, and do the minimal amount of work necessary to get whatever grade is desired. Being part of this Vertical Power team means that people are depending on us to make a high quality product. There are financial and professional repurcussions for the rest of the team if we do not do our job correctly so our motivation must come from a strong work ethic and sense of responsibility.

We are developing a system that must integrate smoothly with the product concept already developed by Vertical Power. Part of our requirement solicitation process is to ensure that our code will integrate with the overall system. Working through this process we have already uncovered several areas where the requirements for other components needed to be more clearly defined or did not cover boundary cases well enough. We are developing our requirements in conjunction with the requirement development process for the rest of the product and in so doing we are uncovering and resolving integration issues now instead of working in isolation and finding out the components don't play well together when it's really too late.

To be honest, David and I have not talked over what strategy we will use to develop our product yet. We have been swamped with understanding the function of our component within the system, defining detailed requirements, and making sure everything will integrate smoothly. The fact that our group only has two people in it is going to make a lot of things easier. We have already committed to two meetings a week with Vertical Power. We have had several working sessions where David and I worked closely together. We are spending time down at Vertical Power working together where any questions that arise can be immediately resolved by talking the issue over with Kevin. Communicaton, communication, communicationis where many software developers fail. The methodology we are pursuing will continue through the design, implementation, and testing processes.

We have not been following the "Waterfall Process", and I don't think anyone really ever does, because as the system requirements are being developed it is impossible, as a programmer, to not be thinking about design and implementation. Too many people skip the design part and think only about implementation when they see a requirement but that is a recipe for failure. We need to look at the big picture first, make sure it makes sense and will probably work, and then move to the fine details of implementation. I believe in top down design and bottom up coding. Creating extremely detailed requirements will facilitate the bottom up coding and unit testing processes while understanding the rationale for the detailed requirements and why they exist will facilitate the top down design and integration testing processes.

Our group is hampered in following any iterative process because our system will be designed to control a microprocessor on a board that doesn't exist yet. We do not have, and many people will smirk at this, the luxury of several beta releases with user testing followed by an eventual alpha release. The timeline for this product requires that we utilize extensive unit testing and integration testing measures to ensure the success of this development. It will be imperative that when the hardware is ready the software will work, and if it doesn't we'll have the test procedures defined to determine where the problem exists. The only way this will happen is by taking the requirements, design, coding, and testing components of this development to the nth degree. We need to follow a process which doesn't really exist yet called "get it right the first time". Everyone knows this is an impossible goal but we need to do our utmost to make it a reality.

The way we will achieve this goal is through top down design and bottom up coding and the requirements this philosophy imposes on the development process.

Journal Assignment #1 - Software Engineering

What I Think of the Software Engineering Process

Marty Ridens
CS460 - Fall 2006
University of New Mexico

I have had some experience in industry having worked as a semiconductor manufacturing engineer for almost 15 years. I was involved in two start-up plants where I was in charge of a large portion of the metrology equipment. In my last effort I negotiated several multi-million dollar deals and have quite a lot of experience on the customer and producer sides of the product development process. I had to specify the requirements for the equipment, perform evaluations of the tools developed by competing companies, create binding cost, delivery, and performance agreements, and present the results of my analysis at very high level meetings for approval by the president and upper management of the company. Internally, I had to create timelines for implementation of the delivered products, train engineers and production workers on the use of the equipment, set performance standards and testing procedures, and guarantee the tools met all specifications.

Now that I have embarked on a second career in computer science, I see the software engineering process as having many similarities to the kind of work I've done before. First and foremost, as product developers, we are part of a team. This team consists of the product designers and developers, the customer or client, the financier if different from the customer, and the end users. Each part of the team brings their expectations and requirements to the table and the software engineering process helps to resolve any differences, communicate exactly what is expected and what will be delivered, and ensure the resulting product fulfills as many of the customers requirements as is possible given budgetary and time constraints. If the developers cannot meet the customer's expectations then this should be flushed out in the early meetings where he still has time to find appropriate alternatives. Essential to this process is a clear understanding of the client's initial requirements and expectations. Changes will occur during the development process but the cost of these changes should be negotiated when they arise. At the onset, any risks should be clearly communicated and all potential failures to meet agreed upon deliverables should be understood.

What we are trying to do is engineer a software solution to a client's requirements within his budgetary and time constraints. Part of the problem is that he might not even have a clear understanding of what the solution is. Clear and frequent communication is the bedrock of this process. If the point of contact is a manager type then communication must be established with the end users to ensure the product will not be ignored or worked around. The delivered product must meet all the requirements of the customer but it must also be usable to those who will be working or playing with it.