Digital media festivals like Canberra’s Enlighten Festival and Vivid Sydney use huge projectors and LED arrays to create a city-sized light show for people to enjoy. Your task in this assignment is to create a micro light show on your micro:bit!
You are going to write an ARM assembly program that uses the LED array on your microbit to create a changing light experience that engages a viewer. The application for your show is a demonstration of your microbit’s LED array and what you can achieve with it!
In order to provide you some inspiration, we’ve set a theme for this year’s light show: Nature. Will you show us how a tree grows from a seed, throwing its shoots bravely out into the world? Or how the rain falls on a cloudy evening? Or even the daily life of a particularly hungry snake which is prone to running into itself? You don’t have to fit the theme if you don’t want to, but perhaps it will help jog your creativity a bit :).
The assignment builds upon what you have learned in labs 6 - 10:
- Lab 7: Basic Machine Code
- Lab 8: Blinky
- Lab 9: Functions, Data Structures and Stack
- Lab 10 & 11: Interrupts and Wrapping Up
For the credit level tasks, you are recommended to at least have completed Lab 10/11 Tasks 1 and 2 The rest of Lab 10/11 is about interrupts, which is useful if you are planning on the D/HD buttons extensions. Other advanced extensions such as sound and networking are covered in Lab 12.
Outline#
- Deadline: 24 May 2024, 11:59 pm
- Assignment template: link
- Specification: keep reading 🙂
- Weighting: 20%
- Marked out of: _ / 100
Rules and Policies#
- this is an individual assessment task, ensure you fork your repo as private
- you may re-use designs / files from your labs
- it is your responsibility to ensure any additional files are included in the repo and pushed to gitlab correctly
- additional files should be left under the
src/
directory - additional files should not contain spaces in their name
- eg:
src/example_file.S
is okay,src/example file.S
is not
- eg:
- you may use the included library files if you wish
- if you want to make changes to the library files, then we suggest you instead create
a new file under
src/
and copy what you need there and modify it; this way we won’t miss extra work that you’re doing
- if you want to make changes to the library files, then we suggest you instead create
a new file under
- your submission must be in ARM assembly, no C or other language is permitted
- late submission is not permitted without an extension
Specification#
Here’s a technical specification for your assignment.
Your program:
- must be written in ARMv7 assembly using the assignment template (link)
- must use the LEDs to create a light show that changes over time
- should use scanning on the LEDs to enable displaying of any 5x5 image
- the light show must sufficiently demonstrate the technical capabilities of your implementation
- must never stop (it can repeat or loop)
- must work when the microbit is powered over USB but not connected to a computer (that is, it works after you upload it and plug into a USB charger)
- should use memory (data structures) to create a changing and easily modifiable light show
- must start with the following image/frame. You are recommended to incorporate this frame into how your light show begins.
Note that you are also provided the LED library from Lab 10/11 in the lib
folder for your convenience.
Report specification#
Your submission must also include a <1000 words design document. This report should cover:
- what your design is, and how it meets the assignment specification (Overview)
- although you should mention briefly what light show you’re displaying, the main focus of this section should be the code design.
- how you accomplished it (Implementation)
- why your design choices were appropriate for the task (Design analysis)
Note that we say < 1000 words. If you feel you have addressed all of what has been asked of you in less words, please don’t feel the need to hit 1000 words. You will end up writing a worse report by reducing the conciseness of it.
Deliverables#
To successfully complete this assignment, the following files must be submitted:
src/main.S
containing your implementationsrc/____.S
any additional files you wish to include or split your implementation across (optional)src/____-lib.S
any files that contain alternative or modified versions of the functions found inlib/___.S
(optional)statement-of-originality.md
containing your name, uid and a list of references for any work that is not your ownreport.md
containing your <1000 word design document- optional
assets/*
containing any images you want to add in your document
- optional
Marking Criteria#
Your assignment will be evaluated on the following criteria:
- Sophistication of your implementation in ARM-v7 assembly language (70/100)
- Sophistication of your design and how it meets the assignment specification (15/100)
- Sophistication of analysis and evaluation of why your implementation is correct and appropriate for your design and what limitations it might have (15/100)
Item 1 will be evaluated primarily through your program code. Items 2 and 3 will be evaluated through your report.md
and the quality of the writing within.
For more information on items 2 and 3, read the design document guide.
For item 1, you can consider the following to be a part of assessing the sophistication of your program:
- your use of memory for encoding your light show
- how easy it is to change what is displaying (a high quality submission should require little / no changes to the code to change what is being displayed)
- your level of extension beyond a basic scanning display
- your style and adherence to assembly programming standards
- includes things like following calling convention and good commenting
- for more information, check the assembly style guide
Ideas For Implementation#
This list is non-exhaustive and is only provided as a guide to give you an idea of what we’re expecting the difficulty of the grade ranges to look like.
Each point is an example of a submission, meaning that you only have to do one point from that grade range (unless otherwise specified). However, the more featured your submission is, the higher the mark. In saying that though, a single high quality feature is probably better than a few low-quality ones.
“Good use of memory”
This means that the program is easily changeable and controllable by modifying data structures in memory, without, or with very little, modification of the code and then uploading it to the board again to view those changes.
This in fact means that you can just have the animation in a data structure in memory, and your code just reads over this data structure to display the animation. This actually makes writing the code easier because it doesn’t rely on what the actual animation is!
Your light show should also contain at least seven distinct images to display. This can either be the individual frames of a moving display, or if you’re making a game this can be the number of different “animations” you define.
These are just provided as a guide and as mentioned, other aspects such as the quality of the report, quality of the programming, etc. also factor in to the grade. This means that just because you have successfully implemented something in grade range X, does not mean that you are guaranteed a grade in range X.
Pass (50 - 59%)#
- Moving Display, Non-scanned, Good use of memory
- Moving Display, Scanned, Poor use of memory
Credit (60 - 69%)#
- Moving Display, Scanned, Good use of memory.
As discussed earlier, completing Lab 10 Tasks 1 and 2 are sufficient if you’re attempting this level of submission.
Distinction (70 - 79%)#
Everything from Credit level and at least one of:
- Basic PWM (Pulse Width Modulation)
- eg: screen level brightness (all LEDs)
- Generative or changing light display using the hardware Random Number Generator
- Using the timer interrupt(s) as an integral part of your display
- Using the temperature sensor peripheral
- Allow using the buttons to dial a particular setting of the animation (e.g. speed or brightness)
- Allow using the buttons to scroll through a number of different animations
Implementations using the button must follow the style guideline that interrupt handlers must be short. See more information here in the Microbit Style Guide. Implementations that do not follow this may be penalised.
If for instance your button runs a second animation but the animation loop code is done in the interrupt handler, this is not good; issues this can cause include the fact that further button presses will have no effect while the interrupt handler (and hence the animation) is running.
High Distinction (80% - 100%)#
An HD is a mark of 80+, not 100. Just because you do something in this range, doesn’t mean that you can expect full marks. Also, the same warning as earlier regarding buttons applies./
Everything from Credit level and at least one of:
- Complex PWM (Pulse Width Modulation)
- eg: per-LED brightness control that can be programmed with memory and change with the display
- External peripherals such as gyroscope, compass and radio/bluetooth (warning: VERY DIFFICULT, consult with your tutor first)
- A higher degree of interactivity using buttons. Requires using both buttons, and a sophisticated state system where the buttons can do different things based on the current state. Examples include a small/simple game, and traversing a menu. See the FAQ item about this as well.
Submission#
Submission is through GitLab, the most recently pushed commit of your fork of the assignment template before the deadline is taken to be your assignment submission.
Getting Started#
- read this assessment page completely
- fork and clone the assessment template
- ensure you fork your project as private
- do NOT change the name or path of the repo, or it may get missed by our software
- plan your assignment and what your are going to implement
- think of how the data structures are going to look and work
- think of how the program is going to fit together
- read the microbit tips and tricks page
- work on each part, debugging, testing, committing and pushing as you go
- make a mistake or get stuck, then ask your tutor in your lab or a good question on the course forum.
Completion Checklist#
- you have submitted the files listed above
- you have wrote all of your code using good practice
- you have saved, committed and pushed your assembly files to gitlab
- you have filled out, committed, and pushed your
statement-of-originality.md
- you have filled out, committed, and pushed your
report.md
- you have checked the report pdf artifact on gitlab to ensure it is correct
- you have checked the gitlab ci tests and they are passing
Report pdf Artifact#
Your repo will be packaged into a report pdf for marking purposes. As such it is important that you
see what the result of the pdf
job is and make sure the output makes sense.
It will:
- take your name and uid from the
statement-of-originality.md
- take your report from
report.md
- take references from the
statement-of-originality.md
- take the code from all of your
src/____.S
files - combine all of them into a single pdf
To view the pdf, first click the ci icon on your most recent commit (as above), then click on the
pdf
job.
Then, you’ll be taken to the job page, where you should see a “Job Artifacts” section, click on the Download
button.
This will download a zip file containing your pdf. Which should look something like this.
There is more general info about gitlab ci here.
FAQ#
What does scanning mean?#
There is a lab exercise for this.
What does sufficiently demonstrate the technical capabilities of your implementation mean?#
This means that your light show, what is actually being displayed on the LEDs, doesn’t need to be long or visually complex. But, it needs to be able to demonstrate what you have implemented.
However, if you’re aiming for a grade of Distinction or High Distinction then the extension will need to be paired with the show in some form of significant way. This means that if you were adding a button for example, then doing something with state where the buttons have some kind of impact would be required, eg: scrolling around a map, controlling a game, exploring a menu (think gameboy menu here).
Let’s use an example: a 7 second loop of a beating heart
Below are some examples of implementation quality and how this loop could be used to demonstrate the capability:
- Moving Display, Scanned, Good use of memory
- This would already be sufficient, assuming that you have encoded the display in memory
- Generative or changing light display using the hardware Random Number Generator
- You modify the beating heart loop to change the size and shape of the heart when it beats based on the result from the random number generator (> 5 variations)
- You make the heart transition through different states (beating, broken, stopped, irregular) based on the result from the random number generator
- Complex PWM (Pulse Width Modulation)
- You modify the beating heart loop to also include a change in brightness for the LEDs when the heart beats, so that the outer LEDs are dimmer, but grow in brightness with the beat
If you’re unsure then post privately on the forum and ask!
What does “higher degree of interactivity” mean? (HD Buttons Extension)#
The most sophisticated form of buttons extension is where, owing to the fact that the screen must respond to user input at a very fine grained level (e.g. every frame, like in a game), the next frame of the animation actually needs to be programmatically calculated based on the current frame and the current “state” of the program. For example, in a Snake game, how the snake looks in the next frame depends on which direction it’s going as well as how it looks on screen right now.
Of course, having statically defined animations in memory that can be run at certain points is possible and even recommended where appropriate. There is also lee-way regarding the level of interactivity; even if your submission doesn’t react dynamically to inputs on every frame, a sophisticated use of state that can be updated by pressing buttons can be sufficient. For instance, you may have a Digital Pet/Tamagotchi where one button scrolls to different screens and the other performs different actions depending on the screen.
Do I have to write a design document?#
Yes! 30% of the marks for this assignment are evaluated through the design document. If you don’t write one you will get zero for that part of the assignment.
How do I write a design document?#
Have a look at the design document page for advice.
Make sure you are answering the questions in the specification and stay within the word limit.
Writing a clear and concise document is a challenge, but we believe in you.
My program doesn’t work, can I email you for help?#
Sorry, you won’t get help over email or Teams. We provide a course forum which is the only way we are able to help.
Forum posts related to your assignment submission must be “private to instructors” (as for any individual assessment task).
It’s [5 minutes, 60 minutes, 12 hours] before the deadline and my CI Jobs aren’t finishing!#
Unfortunately on the day that an assignment is due, when many students are pushing updates at once, the CI servers can’t keep up. You may not see your CI jobs finish before the deadline. You will just have to manually check that your files have been submitted correctly.
The best way to avoid this issue is to start early and finish early 😇
If there’s any issues with your git repository after the deadline. Please let us know (after the deadline) through a private forum post and there may be something we can do.
How do I know my assessment has been submitted?#
If:
- the files in your fork of the assessment are correct (i.e., the files you intend to submit) when checking on the gitlab website
- the time is before the deadline
then your assessment has been submitted (well done!).
Please don’t ask us to “check”, we would be just doing exactly the same thing as the above steps which you can do yourself.