SerTi
Susanna Blomqvist
Antti Korhonen
Heikki Mylläri
Pekka Pakari
Ilkka Urtamo

				Requirement specification 0.7
				24.3.2003

University of Jyväskylä
Department of Mathematical Information Technology

Authors:	Susanna Blomqvist (SBl), Antti Korhonen (AKo), Heikki Mylläri (HMy), Pekka Pakari (PPa) and Ilkka Urtamo (IUr)
Title:	Requirement Specification for SerTi Project
Abstract:	Serti project implements a software called SerialTester for Stresstech Ltd. It will be used to test and monitor equipments controlled via RS232 line. This Requirement specification describes requirements for SerialTester.

Version history:

Table of Contents

1	Introduction
2	Terms, Acronyms and Abbreviations
3	Description of the system
4	Requirements and constraints
4.1	Functional Requirements
4.2	Non-Functional Requirements
4.3	Implementation Requirements
4.4	Constraints
5	Use Cases
5.1	Initialization
5.2	Set and Send Configuration
5.3	Retrieving Status
5.4	Running Motors
5.5	Logging
6	References

1	Introduction
SerialTester will be used to test and monitor equipments controlled via RS232 line (serial port). The software will especially be developed for Stress Logic which is a logical motor driver and I/O board manufactured by Stresstech Ltd. At this moment all testing is made by hand using HyperTerminal, while SerialTester should make the configuring and testing of the system a lot easier.
The document describes the requirements of SerialTester software that will be developed by SerTi project. The project is organized by the Department of Mathematical Information Technology at the University of Jyväskylä. The customer of the project is Stresstech Ltd.
Ilkka Urtamo from Stresstech has written the General Specification document on which this document is based on. The original preliminary version contains an introduction, requirements, use cases, dialog diagram and class model of the program.
Stresstech Ltd has also delivered to project group few other documents. C++ Coding Standard determines the coding standard to be used in the software. SL Communication Specs describes the commands of StressLogic, while Motor Parameters contains a list of parameters for StressLogic.
Project group will also write documents Project Plan (Projektisuunnitelma) and Software Plan. Project Plan describes how the project will be organized and carried out. Software Plan will determine the structure and operations of the software.
Chapter 2 explains some terms and acronyms that are used in the document. Chapter 3 contains a brief description of the system’s structure. In Chapter 4 are defined the requirements and in the Chapter 5 the use cases of the software.
2	Terms, Acronyms and Abbreviations
The following terms are used in the document:
SL	(StressLogic) is a motor driver and an I/O board manufactured by StressTech Oy.	
ST	(SerialTester) is a software to test StressLogic. It will be developed by SerTi project.	
RS232	is a PC serial communication standard.	
I/O	is abbreviation for Input/Output.	
SpyCable	is special 3 headed cable used to monitor RS232 communication between two systems. Third end is connected to the PC in which program logs the messages passed between the monitored systems.	
GUI	is the abbreviation for graphical user interface.	
View/Model	is designing concept where model (core where functionality is) is separated from View (GUI). This means there is no real functionality in GUI classes.	
STL	(Standard Template Library) is a C++ library that provides a set of easily composable C++ container classes and generic algorithms (template functions).	
MFC	(Microsoft Foundation Class) is Microsoft’s class library for Windows based softwares.	

3	Description of the system
Figure 1 represents the structure of the system where StressLogic is used. The SerialTester program to be developed by the project is running in the computer that is connected to StressLogic with a serial cable. Notify that StressLogic is able to control 1 to 3 motor(s), but the software to be developed should control more than 3 motors.

Figure 1. StressLogic in use.

4	Requirements and constraints
The SerialTester software should fulfill the following requirements. They are mainly the same as in the document written by Ilkka Urtamo. Some requirements are supplemented and some are adjusted in the meetings of the SerTi project group.
4.1	Functional Requirements
The following requirements determine the functionality of the program:
1.	Connect and initialize StressLogic.
The program runs command IN (see [2]) to initialize the SL and reports whether there are errors or not.
2.	Send all parameters to StressLogic with one user command.
User can save parameters in a file that is raw ASCII text so it can also be modified with plain text editor. The parameters related to different tests are saved in different files so that user can read the file with ST. User can then easily send all the parameters together to SL. It sends parameters to specific motors and reads the results and sends them back to ST. The parameters of every motor of the test case can be in a same file.
3.	User can save commands in a file and read the file with SerialTester, and then send them to the device.
In SerialTester commands are ran one line at a time by pressing return. In the GUI there is also a button which sends all the commands at once.
4.	User can select all RS232 port settings.
User can choose the settings of serial port, like speed and the port. The changes should take effect without restarting ST.
5.	Store port settings for next use.
When user closes ST all currently used settings are saved to a file so that when the user next time starts ST he doesn’t have to set them again. 
6.	Retrieve motor and I/O status of the StressLogic and view it in human readable way.
When using commands listed in [2], like MLm, StressLogic gives as a response some parameters including hexanumbers. SerialTester should show this information so that it is easy to read and understand. For example motor’s position is presented in location box and status is in status line. There should also be a led for each motor and numbered leds for each I/O, which are 16 inputs and 16 outputs in SL.
7.	User can run motor reference procedure.
With one button can user run motor to the specific ‘reference position’ (‘zero position’). This is also called calibration.
8.	User can run motors by selecting motor, target position and command running.
This means that user can run a certain motor to a specific position by selecting the motor and giving the coordinates where he wants the motor to be ran and which command he wants to use.
9.	User can run motors by pressing buttons.
There are 2 buttons for each motor. User cannot choose the keyboard shortcuts. 
10.	User can set motor and I/O parameters(see [3]).
11.	User can save/load motor and I/O parameters to/from an ASCII file (see [3]).
12.	User can send raw text commands to port.
There is an edit line where user can manually write commands and send them to SL. Also these commands should be added to the log.
13.	User can send commands consecutively.
Next command can be sent before the response of the previus command has arrived. If there is no response after a certain time, it is automatically an error.
14.	User can use copy from log screen.
15.	User can use paste to command field.
16.	User can store the log screen to a specified text file.
There should also be an option whether saving will be done automatically or not. (See also requirement 23.)
17.	User can set ‘mark’ into log screen by pushing defined button/key.
Mark line says “------MARK n” where n is running number describing how many times mark key/button has been pressed/pushed after port opened. There is no need to reset the counter of the mark number during the session.
18.	User can select automatic log scrolling on/off.
19.	User can select the size of log buffer.
20.	Rotating log buffer. Old ones disappear and size does not grow after limit reached.
21.	User can see in the log window all messages sent and received by opened communication port. The messages can be self typed and/or automatically generated by SerialTester.
22.	User can choose earlier sent commands by up/down arrows (Input buffer).
23.	Date, time and information about the command (Send or Received) are part of every command line in log view. Syntax is yyyy-mm-dd hh:mm:ss,s Sent/Recv> Data.
24.	SerialTester doesn’t check the validity of the parameters.
This means that user can give also irrational values for parameters and anyway ST sends them to SL.
25.	There are Pause and Continue commands (see 5.5).
When pressing pause, ST processes the incoming lines but doesn’t show them in the log screen. After pressing continue button ST shows all incoming data in the log screen, including those that were received in pause mode.
4.2	Non-Functional Requirements
These requirements don’t directly appear in the use of the program:
26.	No limit for supported motors.
Although in the GUI there are only three motors available, the other motors can be selected from the menu. The default three motors which are selected when starting ST are saved in the config file.
27.	Port settings can be changed without restarting.
28.	All documents used by SerialTester are ASCII text.
29.	There are four kinds of files. These include files for motor parameters, SL commands, config and log. At the beginning of each file there should be included information of authors, dates and probably additional information. The row should be started with “;” which is the symbol for a comment.
30.	The parameter files can contain comments.
Comments are marked with ;-symbol in the beginning of the comment line. The formulation of the parameter lines is name_of_parameter = value.
4.3	Implementation Requirements
The following requirements are related to the ways of realization:
31.	Log buffer maximum size should be selectable and unlimited (memory limitation).
32.	The software should be designed so that RS232 protocol can be changed to e.g. TCP/IP by reimplementing few classes (uses Interface).
33.	The software has configurable command identifiers. (What is the actual command to be sent to the line?)
The commands are defined in a config file so that if the name or meaning of a some command changes, the program do not need to be changed.
34.	Designed so that target can be changed by changing few classes (uses ‘target interface’).
This means that the classes are well-implemented and instead of SL some other devices could be used as well.
35.	Will not be used hard coded text or target system commands (uses resource files).
This is related to the previous requirements. So in the code there are no references to SL.
36.	View/Model design. 
37.	Windows are resizable.
This requirement is optional.
38.	Model uses standard C++. View is done using MFC and STL libraries.
The program will be done using Microsoft Visual C++, and the code will be written by obeying the C++ Coding Standard [4].
39.	Uses exception handling.
40.	There should be keyboard shortcuts for each motor running in two direction and for mark button.
41.	The function/variable names and the code comments are made in English. The program GUI language is English.
42.	Avoid message boxes unless it is mandatory to user to acknowledge and/or make decision on it to be able to continue. The information messages are shown in different way. There is probably a status line where the most needed information is shown.
4.4	Constraints
43.	Serial Tester do not support X-ray unit testing.
44.	The maximum resolution of GUI is 800x600.
5	Use Cases
The chapter contains a brief description of every situation the program will be used (use case). In every use case the ‘actor’ is user.
5.1	Initialization
Frequency: Always
Preconditions: Target system is powered and operational. SerialTester is running.
Description: User selects “communication setup” command [EXCEPTION: communication port is open]. User edits communication settings and exits the procedure.
User selects “open port” command.
SerialTester opens communication port and sets its parameters [EXCEPTION: Error opening communication port].
User selects “initialization” command [EXCEPTION: Communication port is not open]. SerialTester sends initialization command to target system and compares the response message against what is expected [EXCEPTION: target system not responding ]. Serial tester shows “initialized” message including target system response string.
User selects “close port” command. SerialTester closes and frees the communication port.
Post conditions: Communication port has been opened and closed. Target system is initialized.
EXCEPTIONs:
1.	Communication port is open: Error message is shown. Command is cancelled.
2.	Error opening communication port: Error message is shown.
3.	Communication port is not open: Error message is shown. Command is cancelled.
4.	Target system not responding: Error message including possible target system response string is shown.
5.2	Set and Send Configuration
Frequency: Frequently
Preconditions Target system is powered, operational and initialized. SerialTester is running.
Description: User selects “send configuration”. SerialTester sends last configuration to the target system [EXCEPTION: Error occurred].
User selects “edit configuration” command.
User edits desired settings of motor and i/o parameters. User exits editing configuration [EXCEPTION: value out of range].
User selects “send configuration” command. SerialTester sends just edited configuration to the target system [EXCEPTION: Error occurred].
Post conditions: New, edited configuration has been set to target system.
EXCEPTIONs:
1.	Error occurred: Error message is shown with response string from target system.
2.	Value out of range: Error message is shown with name of the item and the value. Acceptable range is shown in the error message.
5.3	Retrieving Status
Frequency: Frequently
Preconditions: The target system is powered, operational and initialized. SerialTester is running.
Description: User selects the desired motor and then “status” command.
SerialTester sends status query to the target system and receives response string [EXCEPTION: Error occurred]. SerialTester extracts response message and views conditions in human viewable way.
Post conditions: Status of the system I/O and one motor is determined.
EXCEPTIONs:
1.	Error occurred: Error message is shown with response string from target system.
5.4	Running Motors
Frequency: Normal
Preconditions: The target system is powered, operational and initialized. SerialTester is running. The motor parameters are set and sent.
Description: User selects “run reference” command.
SerialTester sends run command to target [EXCEPTION: Motor parameters not sent].
SerialTester shows “running” message during the motor movements. SerialTester sends status messages to target system to determine when command has been executed [EXCEPTION: Motor run error]. When target system informs that it has reached motor reference, SerialTester shows message of reference run has been successfully executed.
User selects motor to be run. User sets target position of the motor.
User selects “run motor” command.
SerialTester sends run command to target [EXCEPTION: Motors not referenced].
SerialTester shows “running” message during the motor movements. SerialTester sends status messages to target system to determine when command has been executed [EXCEPTION: Motor run error]. When target system informs that it motor has reached its target position, SerialTester shows message run has been successfully executed.
Post conditions: Motor has been run to reference position. One motor has been run to desired position.
EXCEPTIONs:
1.	Motor parameters not sent: Error message is shown. Command is cancelled.
2.	Motor run error: Error message including human readable reason as well as reply string from target system is shown. Command execution is cancelled.
3.	Motors not referenced: Error message is shown. Command is cancelled.
5.5	Logging
Frequency: Normal
Preconditions: Two target systems are operational and communicating with each other. Spy cable is connected. SerialTester is running.
Description: User selects “open port” command.
User sees communication between two target systems in the log window. Beginning of the line is date and time when corresponding message has been received. Lines are not cut to next line even if it does not fit into the window.
User presses “mark” key. SerialTester adds mark line to log window [EXCEPTION: Currently receiving line from port]. Mark line say “------MARK n” where n is running number or how many times mark key has been pressed after port opened. SerialTester do not send “MARK” text to the port.
User selects “pause” command. SerialTester processes incoming lines but do not show them in the screen.
User selects “continue” command. SerialTester continues processing incoming lines to log screen.
User selects “close port” command. SerialTester closes and frees the communication port.
User selects “save log” command [EXCEPTION: Port is open].  User selects filename and path of the log file and saves the file. All information in the log window is stored to the file.
Post conditions: Log of communication has been made with marks. Log has been saved to file.
EXCEPTIONs:
1.	Currently receiving line from port: Incoming line is received normally and mark line is added after that. Before next line is processed from the port.
2.	Port is open: Error message is shown, command is cancelled.
6	Conclusion
SerialTester is a software that is used to test and monitor devices through RS232 line. The software is developed for Stresstech Ltd. This document defines the requirements that the software should have. The software will be developed based on these requirements, although there might appear some changes to the requirements during the implementation.
7	References
[1]	Urtamo Ilkka, “SerialTester, General Specification”, Stresstech Ltd. (12-13-2002).
[2]	Pietilä Ilkka, “SL Communication Specs”, Stresstech Ltd. (2002).
[3]	Stresstech Ltd., “Motor Parameters”.
[4]	Hoff Todd, “C++ Coding Standard” (an edited version by Stresstech Ltd.), original version is available in WWW <URL: http://www.possibility.com/Cpp/CppCodingStandard.html>, 06-08-2002.