Team Assignment 1
Barcode reader app
ENG1003, Semester 1, 2017
Due: Sunday April 2nd, 11:55PM (local time)
Worth: 13% of final mark
Aim
Have you ever wondered how barcode readers are able to scan barcodes and figure out the number and the corresponding product? Barcodes are used for tracking by the airline, freight and postal industries, and are also used to identify nearly all products we buy in shops. In fact we even use barcodes to help us identify your team phones for ENG1003. In this assignment, you will work in your teams to develop a mobile web app that uses the phone’s camera to read and decode a barcode and present the corresponding number to the user.
Background
BarkOwed is pet training company that provides both training programs and specialised devices to help owners manage their pet’s training. In particular, BarkOwed specialises in training noisy pets (specifically dogs) to be quiet. As part of their warehouse management, every kind of product that can be mailed to (or collected by) customers is given a unique barcode to aid in identifying products and tracking orders.
Previously their staff used specialised barcode reading devices to enable this however they have found these devices to be inconsistent and in particular they are only designed for UPC barcodes whereas the business would like to move to the more international EAN-13 standard.
As such they have hired two teams to manage the different sides of the project. Your team will be responsible for developing a mobile web app which can read barcodes and display the corresponding number. The other team will work on connecting this app to their existing logistics and supply management software (SupplyAndDemand‘s LSM ®). The reason for this is the software package they are using is proprietary and any changes to it need to be handled by a team from SupplyAndDemand. Your team will need to implement the required functionality for the web app and then provide appropriate guidance to the other team in the form of a handover presentation.
Background: EAN-13 barcodes
EAN-13 barcodes (also known as International Article Number and European Article Number) follow the format given below (most digits have been omitted for conciseness, typically EAN-13 barcodes have 12 digits and 1 check digit).
In the above diagram we use red vertical lines to separate individual parts of the barcode. Each part is broken up into equally sized areas (also referred to as modules) of black and white colour. We show these above with grey borders to make the diagram as easy to understand as possible.
Note: In actual barcodes there are no grey borders separating areas. Instead, a set of three white areas is merely a single white ‘space’ of 3 times the width of one area and a set of four black areas is a ‘bar’ of 4 times the width of one area. Every digit in an EAN-13 barcode will have two bars and two spaces of varying width.
Each EAN-13 barcode begins and ends with a 3-area-wide guard (which are symmetric and the same as each other) of black-white-black. There is a further guard in the centre to distinguish the left and right digits from each other. This centre guard is 5 areas wide and is always white-black-white-black-white.
Each digit is represented by 7 consecutive areas. Digits between the left guard and the centre guard always begin with a white area and end with a black area whereas digits between the centre and right guards always begin with a black area and end with a white area.
Due to the potential dangers of reading a barcode backwards, EAN-13 barcodes use the parity of the number of black areas in each digit to distinguish the left and right characters. Here, Parity refers to whether this number is odd or even.
All digits encoded on the right side of an EAN-13 barcode have even parity (that is to say, the number of black areas in those digits is even). As for the digits on the left side, the leftmost digit always has odd parity (such as in the example above, the first digit (0) has 3 black areas which is odd). Only the leftmost digit needs to have odd parity, the other digits of the left-hand-side are encoded with either an odd or even parity and the pattern of parity values for the six digits is used to specify the first digit of the barcode, which is not directly encoded like the other digits. More on this below.
Background: EAN-13 reference table
Digit
Left (Odd, “L”)
Left (Even, “G”)
Right (Even, “R”)
0
0001101
0100111
1110010
1
0011001
0110011
1100110
2
0010011
0011011
1101100
3
0111101
0100001
1000010
4
0100011
0011101
1011100
5
0110001
0111001
1001110
6
0101111
0000101
1010000
7
0111011
0010001
1000100
8
0110111
0001001
1001000
9
0001011
0010111
1110100
Left/Right Guard
101
Middle Guard
01010
Background: Data format
Your decodeBarcodeFromAreas function will be triggered repeatedly and receive data in the format below
In the top of the image above you can see a visualisation of (part of) a barcode and in the bottom you can see the representation of this as series of values. You should expect to receive a String of zeroes and ones of length 95 specifying the colour of each area in the barcode. This corresponds to the beginning and end guards of length 3, the middle guard of length 5 and twelve digits of length 7 ((12 * 7) + (2 *3) + 5 = 95). Since the first area in the barcode is black, the first character in areas String is a “1”. As the area following it is white, the second character in the string is a “0”. In all cases, a black area will be represented by a “1” and white area will be represented by a “0”.
Background: Calculating the first digit
Each EAN13 barcode includes 13 digits, but only 12 of these (digits 2 to 13) are represented via bars and spaces. So how do we figure out the remaining digit? The first digit (which we shall call the parity digit) can be determined based on the number of ones and zeroes in the six digits between the left guard and the middle guard. As you will have seen in the reference table, digits on the left side of the barcode have two possible encodings, either odd (L) or even (G). This means that the L encodings have an odd number of ones whereas the G encodings have an even number of ones.
After you have decoded the first six digits encoded by the barcode, you will know the parity of each. This gives you a six character parity pattern, which in turn allows you to determine the parity digit of the barcode number via the table below:
LHS parity pattern
Parity digit
LLLLLL
0
LLGLGG
1
LLGGLG
2
LLGGGL
3
LGLLGG
4
LGGLLG
5
LGGGLL
6
LGLGLG
7
LGLGGL
8
LGGLGL
9
For example, given the barcode below
(source: wikipedia commons)
The left section of the barcode is represented by:
8 (L) 0 (L) 0 (G) 0 (G)
6 (G)
5 (L)
0110111 0001101 1001101 1001101
The pattern is LLGGGL and hence the first digit is 3
0000101
0110001
Background: Calculating the checksum
Sometimes, there can be decoding errors caused by misreading the barcode; this would naturally have consequences for identifying the corresponding products. As such, we make use of methods such as checksums to determine whether we have obtained the correct number. For EAN-13 the checksum is calculated as follows.
Every digit has a corresponding position within the barcode, these positions are numbered from the right and the rightmost digit is not included in the calculation of the checksum as it is the check digit that we wish to calculate. However, the parity digit (which was computed from the parity pattern) is included in the checksum calculation.
The checksum is hence computed as each digit multiplied by 1 (where it is at an even position) or 3 (where it is at an odd position). See the table below
Position
12
11
10
9
8
7
6
5
4
3
2
1
Multiplier
1
3
1
3
1
3
1
3
1
3
1
3
By adding the sum of each digit times its multiplier you get the checksum. What is done with this checksum is to take the first multiple of ten above it and subtract your checksum from this to get the check digit.
For example, given the EAN-13 barcode (shown in image above) 3 800065 71113 5, let’s compute the checksum. Sum all digits except the rightmost:
digit
3
8
0
0
0
6
5
7
1
1
1
3
multiplied by
1
3
1
3
1
3
1
3
1
3
1
3
equals
3
24
0
0
0
18
5
21
1
3
1
9
Sum
85
The sum is 85. The next highest multiple of 10 is 90 so the check digit should be 90 – 85 = 5. Looking at the rightmost digit, we see that it is indeed 5, so the barcode is likely correct.
What you are provided with
We have provided a skeleton version of the app. When run, this code displays a page with a video stream from the back-facing camera, It attempts to detect a barcode in the image and it displays a horizontal line to show what it recognises as the extents of the barcode. It also shows short vertical bars on the areas of the camera image it recognises as black bars.
The app skeleton can be found in the ENG1003 resources folder: https://eng1003.monash/resources/
The app skeleton can also be found on the ENG1003 Moodle site
The app skeleton is titled assignment1.zip and contains a file ‘barcode.js’ where you should write your submission.
You don’t need to understand the other files we provide you with as part of the project skeleton — they include some concepts we haven’t yet covered.
What you need to do
Getting started
1. As a team you should download a copy of the project skeleton and unzip this.
2. The ‘assignment1’ folder contains the code of the web app.
3. Open the ‘barcode.js’ file. You will implement your solution in this file.
4. The ‘assignment1’ folder can be uploaded to the ENG1003 web server via the ENG1003 Assignment Uploader web page (see below) and run on your team smartphone.
Programming tasks
The Programming component of this assignment is worth 10% of your unit mark. For the programming tasks, we suggest you complete each part together before moving onto the next one.
Your decodeBarcodeFromAreas function will receive an string of 0s and 1s representing the bars and spaces read from the camera image.
Step 1: Mapping between digits, guards and binary string.
The first task will be to set up structures that maps area patterns (strings of seven zeroes and ones) into digits. You will also need a structure that maps parity patterns (strings of six characters) to the value for the first digit.
Step 2: Finding the guards and collecting sets of bits
Once you have the mapping represented, you should use knowledge of the position of guards and digits to write a loop that extracts the 7-character string for each digit from the input.
Step 3: Converting input data to digits
Now you should take each String of numbers and convert each of them into their corresponding digit, keeping track of the parity of each digit. Be careful to ensure that what you are treating as the left side is in fact the left side (and vice versa); See the EAN13 reference table provided to determine how to do this.
Step 4: Computing the parity digit
Once you have decoded the twelve digits directly encoded into the barcode, you should now be able to determine the parity digit and add this to the beginning of the barcode number.
Step 5: Checking validity (checksum)
Calculate the checksum using the information provided in the background and see if this matches the check digit.
Step 6: Printing and stopping
Your decodeBarcodeFromAreas function should return a JavaScript object containing three properties:
· “barcode”: the (partial or full) String of digits in the barcode number. This should just contain digits with no spaces.
· “message”: a short String containing a status or error message for the user.
· “checksumValid”: a Boolean denoting whether the checksum was correct. If you return an entire barcode (a string of length 13), the app will automatically stop scanning. It will then display a red or green dot depending on whether the checksum for the barcode was valid. The app also displays the message you return.
You should ensure that every possible error state has a unique error message so that it is clear for the end user.
Testing the app
Upload your code to the ENG1003 server using the assignment upload page. It will open the uploaded app, the address of which you can then visit on our team phone. The uploader can be found here:
https://eng1003.monash/uploader/
Advice for best use of the app
· You might find that sometimes the phone’s camera does not focus on an object. If this occurs you should momentarily cover the lens and then uncover it. After this the phone should automatically refocus the camera.
· Holding the phone very steady can help the capture process.
· The barcode recognition works best in even, bright light (i.e., without shadows). Hence, scanning horizontally with a light source above can often work better than scanning something below, e.g., on a desk where the phone can cast a shadow over the barcode.
· The app is designed to be used in portrait orientation. The app does work in landscape orientation too, but the interface is not optimised for this and you will have to scroll the page to see the barcode and output info. Do not worry about this.
Presentation task
This assignment includes a presentation component worth 3% of your unit mark.
In your week 6 prac class you will give a handover presentation. Your team should present an overview of the functionality, the design of the code, and any specific hardware required for its use. You should warn the new team about any current issues in your app, as well as pass on any suggestions you have for improvements.
Format
Each student team will deliver a 10 minute oral presentation (in prac class) describing and demonstrating their app and detailing any issues they encountered. Every member of the team should present for 2-3 minutes.
· The target audience for this presentation is another team who will be extending the project further.
· This presentation would be delivered in a formal business setting and so all team members should be dressed appropriately
· This presentation must discuss the structure and functionality of the application as well as any design decisions made
As with any good presentation, it should be prepared well in advance of the due date (including any visual aids) and it should be well rehearsed as a group and individually.
Submission
Your team should submit their final version of the application code online via Moodle; You must submit the following:
· barcode.js
These should be zipped up with the team name as the filename, e.g., “Team014.zip”.
The submission should be uploaded by the team leader and must be finalised by Sunday April 2nd, 11:55PM (local time)
You also need to individually complete the following tasks (described below)
· CATME peer assessment survey
· Assignment code interview
Your presentation will be given during your practical classes in week 6 (3rd April – 7th April 2017).
Marking criteria
Programming tasks
Your assignment will be assessed based on the version of ‘barcode.js’ file you submit via Moodle. Before submission check your code still works with the original app skeleton, in case you have modified your copy of any of the other files. We will run it with the original app skeleton and test it on your team smartphone. We will use the same phones when marking your assignments.
Assessment criteria:
· Whether the app functionality satisfies the assignment specification
· Quality of app source code, including structure and documentation
You will be marked as a group, however your individual marks will be subject to peer review moderation based on CATME feedback and your assignment interview.
A detailed marking rubric will be available on the unit Moodle page.
CATME Peer Assessment
You are expected to work together as a team on this assignment and contribute roughly equal amounts of work. Peer assessment will be conducted via the CATME online system. You will receive email reminders at the appropriate time.
Not completing the CATME peer assessment component may result in a score of zero for the assignment.
Do:
· Give your teammates accurate and honest feedback for improvement
· Leave a short comment at the end of the survey to justify your rating
· If there are issues/problems, raise them with your team early
· Contact your demonstrators if the problems cannot be solved amongst yourselves Do NOT:
· Opt out of this process or give each person the same rating
· Make an agreement amongst your team to give the same range of mark
Assignment code interview
During your week 6 prac class your demonstrator will spend a few minutes interviewing each team member to individually gauge the student’s personal understanding of your Assignment 1 code. The purpose of this is to ensure that each member of a team has contributed to the assignment and understands the code submitted by the team in their name.
You will be assigned a score based on your interview, and your code mark will be penalised if you are unable to explain your team’s submission:
Category
Description
Penalty
No
understanding
The student has not prepared, cannot answer even the most basic questions and likely has not even seen the code before.
100%
Trivial
understanding
The student may have seen the code before and can answer something partially relevant or correct to a question but they clearly can’t engage in a serious discussion of the code.
30%
Selective understanding
The student gives answers that are partially correct or can answer questions about one area correctly but another not at all. The student has not prepared sufficiently.
20%
Good understanding
The student is reasonably well prepared and can consistently provide answers that are mostly correct, possibly with some prompting. The student may lack confidence or speed in answering.
10%
Complete understanding
The student has clearly prepared and understands the code. They can answer questions correctly and concisely with little to no prompting.
0%
Presentation
Students are marked individually for this assignment on their presentation skills Assessment criteria:
· Voice is of appropriate volume, speed and enthusiasm
· Language is appropriate for a formal context and jargon is only used where necessary (and explained if used)
· Eye contact is consistent and covers most of the audience
· Body language complements the presentation
· Explanations are clear and visual aids used appropriately
A detailed marking rubric will be available on the unit Moodle page.
Other information
Where to get help
There will be FAQ posted in Moodle and updated periodically. You can also ask questions about the assignment on the General Discussion Forum on the unit’s Moodle page. This is the preferred venue for assignment clarification-type questions. You should check this forum (and the News forum) regularly, as the responses of the teaching staff are “official” and can constitute amendments or additions to the assignment specification. Before asking for a clarification, please look at the FAQ and forum.
Plagiarism and collusion
Plagiarism and collusion are serious academic offenses at Monash University. Students must not share their team’s work with any student outside of their team. Students should consult the policy linked below for more information.
https://www.monash.edu/students/academic/policies/academic-integrity See also the video linked on the Moodle page under the Assignment block.
Students involved in collusion or plagiarism will be subject to disciplinary penalties, which can include:
· The work not being assessed
· A zero grade for the unit
· Suspension from the University
· Exclusion from the University
Late submissions
We do not accept late submissions without special consideration. Such special consideration applications should be made to the unit email address with a completed form and supporting documentation within two business days of the assignment deadline. http://www.monash.edu/exams/changes/special-consideration
Unavailable team members
If team members are missing on the day of the presentation, the remaining members should proceed without them. Missing team members will receive a mark of zero unless they are granted special consideration. Such special consideration applications should be made to the unit email address with a completed form and supporting documentation within two business days of the presentation date.
http://www.monash.edu/exams/changes/special-consideration
You must also inform your team members if you will be absent on the day of the presentation.