From d7bd733b1045f71400d1f3d567bf1612d3da521e Mon Sep 17 00:00:00 2001
From: Bennet Blischke <benne.blischket@haw-hamburg.de>
Date: Sat, 9 Nov 2019 18:25:53 +0100
Subject: [PATCH] chore/documentation code & readme

---
 Pipfile         | 12 ++++++++++++
 README.md       | 31 ++++++++++++++++++++++++++++++-
 dump-dvd-kit.py | 16 ++++++++++++----
 3 files changed, 54 insertions(+), 5 deletions(-)
 create mode 100644 Pipfile

diff --git a/Pipfile b/Pipfile
new file mode 100644
index 0000000..dbc05ab
--- /dev/null
+++ b/Pipfile
@@ -0,0 +1,12 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+
+[packages]
+libusb1 = "*"
+
+[requires]
+python_version = "3.7"
diff --git a/README.md b/README.md
index cd8d7cb..3744087 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,34 @@
-A tool to dump the ROM of the Xbox DVD Movie Playback Kit dongle.
+## A tool to dump the ROM of the Xbox DVD Movie Playback Kit dongle.
 
 The ROM is prefixed with version information and the length of the contained XBE.
 The XBE certificate region is the allowed DVD playback region.
 The section of the XBE is compressed using LZX, 128kiB window size, 32kiB blocks.
+
+## Prerequisites
+
+Make sure you satisfy the following requirements:
+
+* basic python know-how
+* pipenv
+* libusb1
+* a way to attach the DVD Kit dongle to your computer i.e. this [[adapter]](https://www.amazon.ca/Mcbazel-Female-Controller-Adapter-Cable/dp/B000RT2868).
+* the dongle itself :)
+
+### Setup
+
+macOS only:
+```sh
+brew install libusb
+```
+
+```sh
+pipenv install
+```
+
+### Usage
+
+Connect the dongle to your computer and run:
+```sh
+pipenv shell
+python dump-dvd-kit.py
+```
\ No newline at end of file
diff --git a/dump-dvd-kit.py b/dump-dvd-kit.py
index 07a007b..ae81cce 100755
--- a/dump-dvd-kit.py
+++ b/dump-dvd-kit.py
@@ -5,6 +5,11 @@
 import usb1
 import struct
 
+REGION_LOOKUP = ["region-free", "North-America", 
+                 "Europe", "Southeast Asia", 
+                 "Latin America", "Africa", 
+                 "China", "MPAA", "International"]
+
 with usb1.USBContext() as context:
 
   vid = 0x045e
@@ -13,15 +18,15 @@
 
   handle = context.openByVendorIDAndProductID(vid, pid, skip_on_error=True)
   if handle is None:
-      # Device not present, or user is not allowed to access device.
-    print("oops?!")
+    print("Device not present, or user is not allowed to access the device")
+    sys.exit()
+
 
   rom_info = 1
   info = handle.controlRead(usb1.REQUEST_TYPE_VENDOR | usb1.RECIPIENT_INTERFACE, rom_info, 0, interface, 6)
 
   (version, code_length) = struct.unpack("<HI", info)
   print("Version: %X.%X" % (version >> 8, version & 0xFF))
-  print("Size: " + str(code_length) + " bytes")
 
   with open("dvd-dongle-rom.bin", 'wb') as f:
 
@@ -44,6 +49,7 @@
       f.write(data)
       remaining -= chunkSize
       cursor += chunkSize
+    print("Size: "+ str(code_length) + " bytes(written to dvd-dongle-rom.bin)")
 
   # Do some sanity checks and print out DVD region
 
@@ -58,4 +64,6 @@
   SizeOfRawData = struct.unpack('I', xbe[SectionHeaders+16:SectionHeaders+20])[0]
   assert(RawData + SizeOfRawData == SizeOfImage)
   GameRegion = struct.unpack('I', xbe[Certificate+160:Certificate+164])[0]
-  print("Region: " + str(GameRegion))
+  print("Region(" + str(GameRegion) + "): " + REGION_LOOKUP[GameRegion])
+
+