Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore/documentation code & readme #3

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

chore/documentation code & readme #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions Pipfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true

[dev-packages]

[packages]
libusb1 = "*"

[requires]
python_version = "3.7"
31 changes: 30 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Member

@JayFoxRox JayFoxRox Nov 14, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the first headline, so it should be #, not ##.
Also remove trailing dot/period if it's no longer a real sentence.

I'd suggest to keep this as a sentence instead.

If we really want to have a headline, we should just use # dump-dvd-kit


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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line should be removed - it's expected when people look at github.

(On a somewhat related note: We might eventually have a CI version which is bundled into a Windows executable, but that's not relevant for now)

* pipenv
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have never used it.

https://github.com/pypa/pipfile implies that it isn't finalized yet?

* 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).
Copy link
Member

@JayFoxRox JayFoxRox Nov 14, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • GitHub markdown should be using [link description] and not [[link description]]?
  • Use amazon.com (instead .ca) if you must

* the dongle itself :)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • No smileys in README please.
  • Capitalize beginnings of sentences


### Setup

macOS only:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be more explanatory to avoid giving the impression that this only works on macOS.
Also Windows and Linux also need specific instructions. In fact, I believe @kl0wn struggled to find a working libusb for Windows in recent past.

```sh
brew install libusb
```

```sh
pipenv install
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume this would have to be run in the cloned git repo folder?

```

### Usage

Connect the dongle to your computer and run:
```sh
pipenv shell
python dump-dvd-kit.py
```
16 changes: 12 additions & 4 deletions dump-dvd-kit.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,11 @@
import usb1
import struct

REGION_LOOKUP = ["region-free", "North-America",
"Europe", "Southeast Asia",
"Latin America", "Africa",
"China", "MPAA", "International"]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are these confirmed to match the region in the dongles?
Why is one of them in all lowercase, but then regions use proper uppercase?

The full list also implies that we have encountered all of those in the real world (which likely isn't the case).
I think it's better to add a dictionary with information, or to just not print this information at all (instead, documenting it on the wiki where we can eventually make sense of it, once confirmed).


with usb1.USBContext() as context:

vid = 0x045e
Expand All @@ -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:

Expand All @@ -44,6 +49,7 @@
f.write(data)
remaining -= chunkSize
cursor += chunkSize
print("Size: "+ str(code_length) + " bytes(written to dvd-dongle-rom.bin)")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add space between "bytes" and "(written".

Maybe just " bytes (dvd-dongle-rom.bin)".

To avoid issues in the future, we might also want to have a temporary variable for the filename (as it's used more than once, and might be changed eventually).


# Do some sanity checks and print out DVD region

Expand All @@ -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])