documentation

master
Henry Jameson 2 months ago
parent 397566c76b
commit e1b4272c21
  1. 129
      README.md
  2. 132
      docs/wangan.md
  3. BIN
      docs/wangan_manual_screencap.png
  4. BIN
      docs/wangan_wiring_photo.jpg
  5. BIN
      docs/wangan_wiring_scheme.png

@ -2,23 +2,56 @@
## What is it?
SugoiDeCard is a small-ish tool I made for sugoi game center in helsinki (you should visit
them!!). It's essentially an unconventional UI for YACardEmu that uses 20x4 LCD and an NFC
reader with the goal to essentially replace old paper-magnetic cards with modern IC cards
such as NESiCA or Aime, potentially it can work with RFID cards, including NFC tags and (heh)
credit cards (not really as supporting those takes some mysterious extra steps), as long as
NFC reader supports those.
Currently only supports 1 cab and 1 game which is Wangan Maxi3DX+ (probably works with older
versions)
## STATUS
- one instance of SugoiDeCard per cab
- multiple cabs potentially possible but no checks are made if card is in used
- card renewal process is yet to be tested
- doesn't like aime cards for some reason even though card reader i use (sorta)
supports them
- currently setting up and configuring YACardEmu is up to user themselves.
SugoiDeCard is a unconventional user interface tool for old arcade games utilizing paper-magnetic
cards, allowing these games to be played with modern arcade IC cards such as Aime™, NESiCA,
Amusement IC or pretty much any NFC or RFID cards.
Originally written by HJ for [Sugoi game center](https://sugoi.fi/) as a hobby project out of desire
to preserve certain game and make it more accessible.
## How it works?
SugoiDeCard starts [YACardEmu](https://github.com/GXTX/YACardEmu) which does the heavy lifting of
the emulating original card-reader device arcade machines use, which SugoDeCard watches for any
change in state (shutter open/close, card present/absent) and uses it to guess the state of the game
using a state machine. It tells YACardEmu to load or insert "card" associated with scanned IC card.
## Status
- Can only ever service one cab per host.
- Does not care about which reader IC card was scanned from
- Architecture is not entirely ready for it yet
- Does not check if card is already in use on other cab on same game
- Only supports Wangan Midnight Maximum Tune 3(DX(+)) game
- Other games can work but yet to be tested and documented
## Limitations
# Save files
Stores saves locally on given directory, directory can potentially be on a
remote drive (SMB/CIFS/WebDAV/NFS). If you're going to use multiple hosts in a
network, however note that there are no check if card is already in use.
Storing game data on NFC card is not supported
and unlikely be supported as arcade IC cards are RFID only, and don't really have
writable storage space, plus storing on the card would require user to leave the
card on the reader, which isn't intuitive
# Game state estimation and concessions
SugoiDeCard tries to estimate game state based on whatever is happening with the
emulated card reader, i.e. initial "idle" state = machine working in "attract" mode,
when card reader's "shutter" (front "door" on an actual reader) is open SugoiDeCard
assumes that game entered login screen (player pressed on gas pedal to start the game)
and game awaits for card to be inserted, shutter closing means login screen ended etc.
This works for most cases but sometimes it can get desynced if something unexpected
happened.
Another thing is that certain features either missing or work differently, mainly due
to different nature of how games handled disposable paper cards and how IC cards are
handled nowadays.
More info about concessions, wiring and more on each game's page:
* [Wangan Midnight Maximum Tune 3DX+](./docs/wangan.md)
## Building and using
@ -26,38 +59,38 @@ versions)
2. `yarn install`
3. `node ./index.js`
You will also need [YACardEmu](https://github.com/GXTX/YACardEmu) built and installed
in `PATH`, or ran somewhere (use `-r` to connect SugoiDeCard to existing YACE instance
instead of starting its own)
## How to use it for actual hardware setup?
You will need following:
- Any device that can run YACardEmu and node.js
- i2c bus, i.e. USB-ISS (don't use USB-I2C) or possibly onboard i2c such as RPi's onboard
i2c buses, but it's up to you to drive I2C the distance if you're planning on using same
machine for multiple cards.
- NFC reader or possibly a smart card reader (not tested), make sure it works with PCSC-Lite
or at least exposes itself as a smartcard reader, there are some "readers" that expose
themselves as a "keyboard" just to enter card's ID - those won't work.
- Serial port (USB-to-serial will work)
- Wangan Maxi3(DX(+)) cab, some cabling, anything you might need to connect serial port to the
machine. (TODO: Schematics for cabling)
- Present/disused card data is essentially discarded
- Upgrading cards (i.e. 3 -> 3DX, 2 -> 3 etc) is untested
Example working setup with a rpi:
TODO: make an image for pi
1. RPi3 will be driving (hehe) the whole thing
2. USB-ISS is used for I2C communications, connected to 20x4 character LCD via a
i2c "backpack". (currently only 20x4 display is supported, smaller screens
most likely won't be supported because we put up instructions there and there's
quite a lot of them even for a 20x4 screen)
1. devantech driver is used to expose USB-ISS as a syste
3. USB-Serial (RS-232 9pin DSub) is used with a breakout adapter, connected to
wangan midnight's mainboard (same port for steering wheel and for card reader!)
4. DietPi used as an OS.
5. Both YACardEmu and SugoiDeCard are started as SystemD services. 8082 is used
for communication between the two.
- Any device that can run node.js and (preferably) (GNU/)Linux
- Raspberry Pi 3 works fine
- Any generic modern x86_64 IBM-PC works fine
- A PC/SC-compatible NFC reader. (pcscd and pcsc-lite will be used)
- ACR122U works fine out of the box.
- Sony FeliCa (Aime) cards somewhat work but need improvement
- ACR1252U should also work but that remains to be tested
- Elexlinco NC004 (shows as GHI NC001) works but you'll need to add it to `libccid_Info.plist`
to make it appear in pcscd
- Does not work with Sony FeliCa (Aime) cards **at all** (reader just doesn't react to them)
- Readers can react to bank cards or ID cards but this currently might crash SugoiDeCard
- Regular smart cards and readers (i.e magnet strip or chip) could potentially work but untested
(and probably never will)
- RS232 (or potentially RS485 for other games) serial port (i.e. COM port)
- USB adapters and built-in DB9 COM ports should work fine, but you'll probably need a breakout adapter
to connect game to it.
- RaspberryPI's GPIO should also work fine if configured properly.
- I2C bus and display (optional but highly recommended)
- I2C bus
- Built-in I2C bus on RaspberryPI can work, but this will have limitations on how long cable can be.
so far, using a USB adapter is preferable.
- USB-I2C **DOES NOT WORK**
- USB-ISS does work but you'll need this [kernel module](https://github.com/milidam/devantech) to make
it work as a regular I2C bus.
- 20x4 LCD display with HD44780 controller, adafruit and many hobby electronics stores sell them
- I2C "backpack" for LCD display mentioned above. Some stores sell those LCD displays with I2C
backpacks already soldered in

@ -0,0 +1,132 @@
# Wangan Midnight Maximum Tune
## Versions supported
- Full support and tested
- Wangan Midnight Maximum Tune 3 (Export)
- Wangan Midnight Maximum Tune 3DX+ (Export, Japan)
- Should also work just fine
- Wangan Midnight Maximum Tune 3DX
- Other regions (china?) of wangan midnight 3(DX(+))
- Not tested but should potentially work
- Wangan Midnight Maximum Tune 1
- Wangan Midnight Maximum Tune 2
## Versions not supported
- Wangan Midnight Maximum Tune 4 onwards (use IC cards already)
## Wiring info:
> Following is mostly an example, colors are reference of what I've seen on two
real arcade machines but might differ, pinout should be the same, however. Also,
only applies for Wangan Midnight Maximum Tune 3DX+, previous versions may or may
not have different connections and/or cable colors.
Game communicates with card reader using a standard serial (RS-232) interface, but
uses 3 pins and a non-standard (i.e. not D-Sub) connector. There is a 8 pin JST connector
on game's case:
![Segment from WMMT3 operator's manual](./wangan_manual_screencap.png)
Looks like this:
![Photo showing the connector](./wangan_wiring_photo.jpg)
First 3 wires are for force feedback controller/motor, last 3 wires are for card reader
You'll need to disconnect those and connect them to device running SugoiDeCard and YACardEmu
Here's an example wiring for connecting to a DB9 connector:
![Wiring diagram](./wangan_wiring_scheme.png)
RX and TX need to be connected cross-over (i.e. RX on game to TX on emulator and
vice-versa). Two pins on game side are left unused and not connected to anything
If you're planning on switching between emulated card reader and real one it's
probably a good idea to make a Y cable or additional custom connector just for
card reader side.
**NOTICE**: Sometimes game can get stuck showing an error for either card reader or
force-feedback which *will* persists between soft reboots, this can be fixed by
hard-rebooting (i.e. power-cycling) the machine.
## Concessions
### New card registration
Originally paper cards could be purchased from game itself for extra price, which
is contrast to buying modern IC cards from arcade operator or elsewhere. This makes
new IC card registration somewhat unintuitive - you'll need to scan your card, select
"no card" and then "buy new card", even though game happily gives away cards in freeplay
mode.
LCD display will display instructions as a workaround for this.
Potentially, if game running is a decrypted/modified version, this could potentially be
fixed by messing with game's localization strings and sprites.
### Present/disused vehicle cards
Original paper cards had a "feature" that they have limited use of 60 games (cards themselves
physically can endure many more rewrite cycles, it's purely marketing trick) after which they
must be renewed (internally game calls it "overhaul" which makes sense in car tuning world, but
game itself never refers to it as that, I wonder why), in which you're essentially buying a new
card, and your old card becomes a "Present card" (or "Disused vehicle card" depending how far
you were in story mode) which in theory you could give away to your friend and after they played
it for 5 times it would create one or several new cards with identical pre-tuned car on it.
Additionally, when renewing card you'll be able to pick a new custom color.
This whole ordeal is very nice and cool and potentially extracts even more money out of players,
and cards themselves can be a nice memorabilia but otherwise it's mostly annoying and useless.
Implementing it would also take extra effort as well as some hoops to jump through for the player,
so those are not supported right now.
We might implement saving present card data separately, so that it could be transferred to a real
card if somebody *really* wants physical memorabilia.
### AAAAA Player or pseudo-guest play.
Since original paper cards are purchased from game itself, card reader comes with a built-in
dispenser that arcade operator supposed to fill with blank cards (used cards also work), this
dispenser has empty/full status, so that when it's empty game won't "sell" new cards and only
allow either guest play or playing with existing card (as long as it doesn't need renewal).
Game seem to only read dispenser status at boot (and after dispensing a card?), which means
if you "refill" the dispenser (either real or emulated) you'll need to restart the game for
it to recognize that it can dispense more cards. As a result, we can't really force guest
play (unless we also hack into JVS?) if no card was scanned, so we do a pseudo "guest play"
meaning YACE will just write data to a dummy file (`dummy.bin`) and essentially discard all
of the save data created this way. This is mostly harmless but it might fill the high scores
and ghost data with players named AAAAA.
## Game state estimation and issues.
Currently, our only source of information are card and shutter status of the card reader,
as result we can only guess what is actually happening with the game at the moment. This works
for 90% of supported cases but can get out of sync if anything unexpected happens. This also
means than initial state must be synchronized manually, i.e. currently it means you must start
SugoiDeCard when game is in attract (or similar, i.e. real guest play) mode. There are some
safety timeouts in some cases so that if it does get stuck you might get it un-stuck simply by
waiting, but certain cases might require manual reboot.
### Note about renewal
Current version of SugoiDeCard does not have save data parsing, so it has no idea if card needs
renewal or not, since card renewal involves ejecting old card this eject must be ignored, otherwise
it would be treated as a "game over" and renewed card's data would be discarded. To account for this
we wait for a while right after inserting existing card and wait for ejection. In future we might
add optional (since save data is encrypted and you'll need to get keys yourself) save file parsing
to streamline the process.
### Stuck situations
#### Service/Test buttons
Going to service menu automatically ejects card, if this happened while SugoiDeCard was checking
for card renewal, it might get stuck in "playing" state indefinably (needs testing). Otherwise this
ejection would be handled as a regular "game over".
Going to service menu seems to leave shutter in whatever state it was in, i.e. going to service
menu at login screen ("Do you have a card?") will leave shutter open, booting SugoiDeCard in this
state will immediately switch it into "accepting card" state, but it should eventually fall back
to guest playing state and then to idle, if you just wait.
#### Unexpected situations
Any error with save data that could cause game to reject the card (i.e. trying to load japanese
save data on export game, corrupt data) would cause SugoiDeCard immediately switch to "card renewed"
state and possibly get stuck forever in it (needs testing and fixing)
Any connectivity loss (i.e. cable disconnecting, cab losing power/restarting unexpectedly) cannot be
detected at all (as there seemingly no heartbeats between card reader and game board), and will most
likely lead to a desynced state, although when game powers up it will automatically eject the card
so in case of unexpected reboot this ejection would be treated as a "game over".
If machine running SugoiDeCard loses power or if connection breaks, game machine will error out trying
to write the data, however it will write data to a internal backup (5 slots) which *could* be re-written
to card, but SugoiDeCard currently *does not support this at all*.

Binary file not shown.

After

Width:  |  Height:  |  Size: 350 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 310 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 55 KiB

Loading…
Cancel
Save