F28HS: Hardware-Software Interface CW2: Systems Programming (60%) v1.0 2024/25
Assessed Coursework 2 — Systems Programming
1 Overview
The aim of this coursework is to develop a simple, systems-level application in C and ARM Assembler, running on a Raspberry Pi with attached devices.
The learning objective of this coursework is for students to obtain detailed understanding of the interaction beween embedded hardware and external devices, in order to control this interaction in low-level code. The programming skills will cover detailed resource management and time sensitive operations. Design choices regarding languages, tools, and libraries chosen for the implementation need to be justified in the accompanying report. This coursework will develop personal abilities in articulating system-level operations and identifying performance implications of given systems through the written report that should accompany the complete implementation.
The report needs to critically reflect on the software development process for (embedded) systems programming contrast it to main stream programming, and comment on performance-relevant design choices as well as impact on resource consumption.
This CW should be done in pairs, using group-sets in Canvas. Team up with a fellow student on the course and sign-up to one group on Canvas under People -> Group.
2 Lab Environment
Hardware environment: As hardware platform, a Raspberry Pi 2, 3 or 4 (not 5) with the starter kit introduced in the course should be used. For Edinburgh students, you can get these by email ap- pointment from “Hurt, Adrian” <A.C.Hurt@hw.ac.uk>. The Raspberry Pi can be directly connected to the machines in the Linux Lab (EM 2.50) using a KVM switch. See the Lecture slides (“Course Overview”) and the technical HOWTOs (Canvas) on this topic. You can then use the keyboard and mouse for input and the monitor for output and work as if on a standard Linux machine.
Software environment: The SD card that is part of the starter kit uses Raspberry OS (32-bit) as Linux-based operating system. It is recommended that you stick to this version, although there might be a more recent version of Raspbian available. If you are installing Raspberry Pi OS yourself, make sure that you are using the 32-bit version, otherwise assembler code will not work as expected.
For developing the code you should use the standard GNU toolchain (gcc, as, ld) that comes with the version of Raspbian that is installed on the SD card. It is strongly recommended that you use the GNU debugger (gdb) for debugging your code. To check for and debug memory errors, we recommend that you use GCC’s Address Sanitizer. See the Lecture slides in the Programming Languages track of the course.
3 Embedded Systems Programming: Master Mind Application
In this assignment, you are required to implement a simple instance of the MasterMind board-game, us- ing C and ARM assembler as implementation language. The application needs to run on an Raspberry Pi 2, 3 or 4 (not 5), with the following attached devices: two LEDs, a button, and an LCD (with attached
This coursework specification, and the example code provided during the course, is Copyright 2025 Heriot-Watt University. Distributing this coursework specification or your solution to it outside the univer- sity is academic misconduct and a violation of copyright law.
Deadline: see Canvas module
F28HS: Hardware-Software Interface CW2: Systems Programming (60%) v1.0 2024/25 potentiometer for controlling contrast). The devices should be connected to the RPi via a breadboard,
using the RPi kit that was handed out early in the course.
Application: MasterMind is a two player game between a codekeeper and a codebreaker. Before the game, a sequence length of N and a number of C colours for an arbitrary number of pegs are fixed. Then the codekeeper selects N coloured pegs and places them into a sequence of N slots. This (hidden) sequence comprises the code that should be broken. In turns, the codebreaker tries to guess the hidden sequence, by composing a sequence of N coloured pegs, choosing from the C colours. In each turn the codekeeper answers by stating how many pegs in the guess sequence are both of the right colour and at the right position, and how many pegs are of the right colour but not in the right position. The codebreaker uses this information in order to refine their guess in the next round. The game is over when the codebreaker successfully guesses the code, or if a fixed number of turns has been played. For details see this MasterMind Wikipedia page. If you can’t access Wikipedia, use this local copy of the Wikipedia page. (Creative Commons 4.0. Source: Wikipedia)
Below is a sample sequence of moves (R red, G green, B blue) for the board-game:
Secret: R G G
================
Guess1: B R G
Answ1:
Guess2: R B G
Answ2:
Guess3: R G G
Answ3:
11 20 3 0
Game finished in 3 moves.
This is the sample sequence of input (IN) and output (OUT) operations in the running application when picking the Secret, followed by the first Guess1 and the first Answ1, corresponding to the example above. This uses an encoding of 1 for R (red), 2 for G (green) and 3 for B (blue). Press 1 means, press the button once, Green Blink 1 means blink the green LED once etc; // starts a comment for this example and is not part of the input/output):
OUT: Secret: 1 2 2 // show secret
IN: <Press 3> <Pause> // first input
OUT: <Red Blink> // first input accepted
OUT: <Green Blink 3> // echo the input value
IN: <Press 1> <Pause> // second input
OUT: <Red Blink> // second input accepted
OUT: <Green Blink 1> // echo the input value
IN: <Press 2> <pause> // third input
OUT: <Red Blink>
OUT: <Green Blink 2>
OUT: <Red Blink 2>
OUT: <Green Blink 1>
OUT: <Red Blink 1>
OUT: <Green Blink 1>
OUT: <Red Blink 3>
...
// third input accepted
// echo the input value
// input completed
// first no. in answer (exact matches)
// separator
// second no. in answer (contained matches)
// next round starts
// next round
Deadline: see Canvas module
F28HS: Hardware-Software Interface CW2: Systems Programming (60%) v1.0 2024/25
Coding: The application should be developed on the Raspberry Pi 2, 3 or 4 (not 5), using the device configuration below, with inlined ARM assembler code to directly control the attached devices through GPIO connections. No external libraries for programming the devices should be used in the final ap- plication. It is recommended to encode the C colours as numbers from 1 to C, and to display the sequence of pegs as a sequence of numbers. To test the application, a setting of 3 colours (C=3) and a sequence length of 3 should be used (N=3). In a “debug” mode the program should print the secret sequence at the beginning, so that the answers given can be checked, and each entered sequence (the guess) with the corresponding answer (as 2 numbers).
Wiring/Devices: Two LEDs should be used as output devices: one (green) LED for data, and another (red) LED for control information (e.g. to separate parts of the input and to start a new round). The green data LED (right) should be connected to the RPi using GPIO pin 26. The red control LED (left) should be connected to the RPi using GPIO pin 5. A button should be used as input device. It should be connected to GPIO pin 19. An LCD should be used as an additional output device. It should be connected as follows:
LCD 1 2 3 4 (RS) 5 (RW) 6 (EN) 7 8
GPIO (GND) (3v Power) (Potentiometer) 25 (GND) 24 (unused) (unused)
LCD 9 10 11 (DATA4) 12 (DATA5) 13 (DATA6) 14 (DATA7) 15 (LED+) 16 (LED-)
GPIO (unused) (unused) 23 10 27 22 (3v Power) (GND)
This means that the 4 data connections to the LCD display are connected to these 4 GPIO pins on the RPi: 23, 10, 27, 22. All devices should be connected to the RPi using a breadboard. Below is a Fritzing diagram that visualises the entire wiring: Note that the middle pin of the potentiometer needs to be wired to LCD 3, and the other 2 legs to ground and power as shown in this version. Also, use the 3.3V and not the 5V power GPIO pin from the RPi to be on the safe side.. You can connect the RPi GPIO pins directly to the LCD pins, or plug the LCD directly into the breadboard, but it’s usally easier to use a breadboard as shown.
Deadline: see Canvas module
F28HS: Hardware-Software Interface CW2: Systems Programming (60%) v1.0 2024/25
LCD: Follow the information in the diagram above. To get a closer look at the wiring, you can (but don’t have to) download the project file of the above Fritzing diagram application here. You can view it using the Fritzing diagram application. Follow this FAQ on how to download and install the Fritzing diagram application. The main advantage of viewing the diagram inside the application is that you can zoom in to examine the wiring, and you get info on the pin numbers when you hover the mouse over them. All this is optional, and can work just with the diagram above, and the pin numbers shown in the diagram.
Sample code for the control of LED, button and LCD can be found on the sample sources sec- tion of the Course Information page for F28HS. Note that the low-level operations of setting the mode of a pin, writing to an LED or LCD, and reading from a button need to be encoded in ARM Assembler. Prototypes for these functions digitalWrite, pinMode, writeLED, readButton, waitForButton, are given in the file lcdBinary.c in the gitlab repo, and the code for these func- tions needs to be completed. The matching function also needs to be implemented in ARM As- sembler, and the code in file mm-matches.s needs to be completed (see below). It’s recommended, though, that you first develop a pure C implementation, and then replace the C functions for the above operations with ARM Assembler functions. The rest can be done in C, and you can draw on the sample code to build the functionality of the application.
It is strongly recommended that you do the lab sheets for LED, LCD and button control, before starting the CW. However, you may have to adapt the wiring used in the lab-sheets to the one prescribed in the CW spec.
Deadline: see Canvas module
F28HS: Hardware-Software Interface CW2: Systems Programming (60%) v1.0 2024/25
Game functionality in C: The game logic of the application (written in C) must provide the following functionality, with the application acting as codekeeper (i.e. generating a random, hidden sequence and answering) and the user as code breaker (i.e. entering guess sequences) (see the sample sequence above):
1. Greeting: At start the RPi should show a personalised greeting, based on the first team members’ family name: have the RPi blink one red for every consonant and 1 green for every vowel in your surname (first 5 letters only). For example, for the surname “Smith” expect this sequence of LED blinks (at each time only one colour should be on): red, red, green, red, red
2. Theapplicationproceedsinroundsofguessesandanswers,asinthesamplefortheboardgame.
3. In each round the player enters a sequence of numbers.
4. A number is entered using the button as an input device. Each number is entered as the number of button presses, i.e. press twice for an input of two etc.
5. A fixed time-out should be used to separate the input of successive numbers. Use timers (either on C or Assembler level), as introduced in the lectures.
6. The red control LED should blink once to acknowledge input of a number.
7. Then the green data LED should repeat the input number by blinking as many times as the button has been pressed.
8. Repeat this sequence of button-input and LED-echo for each element of the input sequence.
9. Once all values have been entered and echoed, the red control LED should blink two times to indicate the end of the input.
10. As an answer to the guess sequence, the application has to calculate the numbers of exact matches (same colour and location) and approximate matches (same colour but different loca- tion).
11. To communicate the answer, the green data LED should first blink the number of exact matches. Then, as a separator, the red control LED should blink once. Finally, the green data LED should blink the number of approximate matches.
12. Finally, the red control LED should blink three times to indicate the start of a new round.
13. If the hidden sequence has been guessed successfully, the green LED should blink three times while the red LED is turned on, otherwise the application should enter the next turn.
14. When an LCD is connected, the output of exact and approximate matches should additionally be displayed as two separate numbers on an 16x2 LCD display (see below).
15. On successful finish, a message “SUCCESS” should be printed on the LCD, followed by the number of attempts required.
Note: The Raspberry Pi should act as codekeeper, so needs to generate a (secret) random se- quence and answer with the number of exact and approximate matches in the sequence above.
Deadline: see Canvas module
F28HS: Hardware-Software Interface CW2: Systems Programming (60%) v1.0 2024/25 Command-line usage: The application shall provide a command-line interface to test its functionality
in an automated way, like this:
./cw2 [-v] [-d] [-u <seq1> <seq2>] [-s <secret sequence>]
If run without any options, the program should show the behaviour specified above. If run with the -d option it should run in debug mode, and show the secret sequence, the guessed sequence and the answer, as shown in the example above. If run with the -s option, the <secret sequence> should be used as the sequence to guess (this is useful in combination with the -d option to debug the program). If run with the -u option, it should run a unit test on 2 input sequences, <seq1> and <seq2>, and print the number of exact and approximate matches, e.g.
./cw2 -u 123 321
should print (on the terminal, just for debugging)
1 exact
2 approximate
Matching function in ARM Assembler: The matching function for sequences, as described above should be implemented in ARM Assembler code and used in the C program for the game logic. An ARM Assembler sub-routine, matching ARM sub-routine calling conventions (AAPCS), should be implemented, either in a separate Assembler file or as inline Assembler, and be used from the C code to determine the number of exact and approximate matches as explained above. During development it’s recommended that you first develop a pure C implementation of the matching function, and to use this version in order to test the game logic of the program. Then, move on and replace the C function for the matching function with an ARM Assembler function.
GitLab repository: To start your project fork the following GitLab repository , and then clone your forked copy onto a local machine. Ideally, do this directly on the Raspberry Pi. If you don’t have a network connection, clone onto a local machine and then transfer the files to the Raspberry Pi, using for example a USB stick. Remember, you can develop the C parts, including unit testing for the matching function, on any Linux machine, and the repo contains a CI script for automated unit testing, using the -u option. The GitLab repo contains template code with a suggested structure for the master mind C program in master-mind.c and for the ARM Assembler matching function in mm-matches.s. Check the comments in these two files as well as the top-level README.md file in the GitLab repository.
Testing: Use the unit testing provided in the templates for C and Assembler code, to test the matching function, and report the results (number of successful tests) in your report. Unit tests are triggered au- tomatically in the CI pipeline when you upload a new version to GitLab. Beyond this, test the game logic of the application by running the game (in debug mode, which shows the secret sequence at the begin- ning) with a given secret sequence (using the -s option) until you find the secret sequence. Add the sequence of interactions as screenshot or cut-and-paste text to the report. Also, run a unit-testing setup (using the -u option) with the sequences 121 and 313) and show the result: ./cw2 -u 121 313
Deadline: see Canvas module
F28HS: Hardware-Software Interface CW2: Systems Programming (60%) v1.0 2024/25 4 Submission
You must submit the complete project files, containing the source code, the compiled cw2 executable, and the report (in .pdf format) as one .zip file. Submission is due through the Coursework 2 assign- ment on Canvas. Please check the assignment details on Canvas to see your submission deadline — different campuses may have different deadlines. The main executable driving the application should be called cw2, as discussed in “Command-line Usage” above. This coursework is worth 60% of the module’s mark (including 6% for the assessed lab).
The submitted coursework needs to be demonstrated, by both team members, in the lab slot of Week 12. Demonstration is mandatory and no marks will be awared to submissions that have not been demonstrated.
You are marked for the functionality of the application, but also for code quality and the discussion in the short report. The marking scheme for this project is attached. This project should be done in pairs. Following the submission, there might be selected demos for submissions that don’t sufficiently explain behaviour in the report.
Late Submission Policy
The standard penalty of -30% of the maximum available mark applies to late submissions. No submis-
sions will be accepted after 5 working days beyond the submission deadline.
5 Report Format
The report should have about 2 – 5 pages and needs to cover the following:
• A short problem specification
• The hardware specification and wiring that is used as hardware platform
• A short discussion of the code structure, specifying the functionality of the main functions.
• A discussion of performance-relevant design decisions, and implications on resource consump- tion.
• A list of functions directly accessing the hardware (for LEDs, Button, and LCD display) and which parts of the function use assembler and which use C
• The name and an interface discussion (what are the inputs, what is the output of the sub-routine) of the matching function implemented in ARM Assembler.
• An example set of output from the application running a complete game
• Asummary,coveringwhatwasachieved(andwhatnot),outstandingfeatures,andwhatyouhave learnt from this coursework
Deadline: see Canvas module
F28HS: Hardware-Software Interface CW2: Systems Programming (60%) v1.0 Marking Scheme
2024/25
Marks
Criteria
Meeting system requirements and functionality (as specified in Section 3) 38 Report Quality 8 Contents matching the structure in Section 5; discussion of program logic and of
the core functions, controlling the GPIO interface; summary of learning outcomes achieved.
The Application 8 Code quality (both C and ARM Assembler), clear function interfaces, sufficient comments.
Assessed Lab 6 The implementation of the “Traffic Lights” lab needs to be demo’ed in a lab slot.
Total marks 60
Generative AI Usage Policy
Our policy on the use of generative AI tools in F28HS is as follows:
• Where English is not your first language you may use GenAI to translate the assessment instruc- tions or other relevant content. You may not use GenAI to translate your assessment answers - you must write them in English, as HW requires all work to be completed in English and to be your own work.
• No GenAI generated content is permitted in your assessment submission.
• You should ensure that any use of GenAI to support your assessment planning is identified in
your notes to ensure that you do not unintentionally use it in the assessment.
This covers your use of tools such as ChatGPT, GitHub Copilot and other “AI search” or “code comple- tion” tools. You must not use these tools to generate text or code for F28HS. We will report suspected use of generative AI as academic misconduct.
Deadline: see Canvas module
F28HS: Hardware-Software Interface CW2: Systems Programming (60%) v1.0 2024/25 Academic Misconduct
Your attention is drawn to the university policy on academic misconduct and to the Contract Cheating Risk and Avoidance Guide (available on Canvas).
This is a pair project and you will have to identify the contributions of each group member in the report. Each group member needs to contribute a substantial implementation task to the project.
The code you submit must be the work of either of the two group members. If some text or code in the coursework has been taken from other sources (beyond the material provided for this course), you must give a clear reference to the source in comments in the code or the report. We cannot give any marks for work that is not your own.
Failure to clearly reference work that has been obtained from other sources, or copying the words or code of another student (other than the group members), is plagiarism.
Asking a third party to complete coursework on your behalf, and then submitting it as your own work, is contract cheating.
You must never give a copy of your coursework writing or code to another student (other than the group members), and you must always refuse any request from another student for a copy of your coursework. Sharing your coursework with another student (other than the group mem- bers) is collusion.
Suspected plagiarism, contract cheating or collusion will be referred to the School Discipline Committee for investigation. This will delay your feedback, and if you are found guilty of mis- conduct then it will result in a penalty such as voiding the course or being withdrawn from the university.
The use of AI generation and code completion tools is not acceptable.
So please don’t do any of the things above! If you have any concerns about potential academic misconduct, please ask your local course leader for guidance.
For details see the University’s academic misconduct policy.
Deadline: see Canvas module
請加QQ：99515681 郵箱：99515681@qq.com WX：codinghelp
