pmnxis / billmock-app-rs

BillMock firmware source code written in rust

billmock-app-rs

Rust Embedded firmware using rust embedded-hal¹ and embassy-rs² on STM32G030C8³ MCU for Billmock product.

Used rust experimentally.

This repository is aiming three goal. One for development of production firmware and second is making a proof of concept that rust embedded is usable for actual embedded production. And last goal is setting some example about production-rust-embedded-code.

This project is currently under development, with ongoing QA testing and some optimization remaining.

Billmock

Detail documentation is here BillMock Manual

It is hardware and software for the purpose of converting I/O signals related to money payment of arcade game machines for compatibility.

This project began development at the request of GPARK Co., Ltd⁴ and was designed and developed for the using credit card readers in arcade game machine and compatibility of existing payment systems (open-drain-based), and is open to the public except for code in the NDA area. The project has been granted an open source disclosure except of NDA era.

Target Hardware

Based on BillMock-HW 0.5 mini, 0.4 mini and 0.4.
0.2 and 0.3 HW bring-up codes are still left for recyle the old PCB.

• 0.2 HW has different gpio configuration compare to latest boards.
• 0.3 HW has minor bugs, floating on VendSide-Inhibit and missing net route on VendSide-1P-StartJam.
• 0.4 HW fixed 0.3 HW bugs.
• 0.4 HW mini reduced BOM for mass-manufacturing
• 0.5 HW mini added tact switch for SVC mode call

Current default HW is 0.5 mini. If need to use old 0.4 or 0.4 mini, following below command lines

cargo build --features hw_0v4 --no-default-features --release
cargo build --features hw_mini_0v4 --no-default-features --release

Target hardware image

The hardware revision currently adopted for final mass production is 0.5-MINI, and the software development is also progressing according to this version.

Old revisions.

Hardware design

BillMock hardware schematic repository (only pdf) https://github.com/pmnxis/BillMock-HW-RELEASE

The schematic printed in PDF is distributed under CC BY-SA 3.0, but the actual Gerber files and project files are private.

v 0.5 Mini (2023-10-24)

BillMock-Mini-HW-0v5.pdf

v 0.4 Mini (2023-09-12 or 2023-09-13)

BillMock-Mini-HW-0v4.pdf

v 0.4 (2023-09-08)

BillMock-HW-0v4.pdf

v 0.3 (2023-08-11) - DEPRECATED

BillMock-HW-0v3.pdf

v 0.2 (2023-06-13) - DEPRECATED

BillMock-HW-0v2.pdf

Feature diagram

Dependencies

See details here dependencies

NDA Dependencies

• Dependency Injection for card reader
• Detail stories

License

This program and the accompanying materials are made available under the terms of the Apache Software License 2.0 which is available at https://www.apache.org/licenses/LICENSE-2.0, or the MIT license which is available at https://opensource.org/licenses/MIT

Also all of codes are based one MIT or Apache Software License 2.0. But some common *.toml files are based on CC0-1.0 license. (Example Cargo.toml)

Footnote

1 rust embedded-hal is hardware abstraction layer written in rust
( https://github.com/rust-embedded/embedded-hal )

2 embassy-rs is rust embedded framework
( https://github.com/embassy-rs/embassy )

3 STM32G030C8 is STMicroelectronics' MCU with ARM-Cortex M0+ , 64KiB Flash and 8KiB SRAM.
( https://www.st.com/en/microcontrollers-microprocessors/stm32g030c8.html )

4: GPARK Co., Ltd. is a company in South Korea that operates the arcade game industry.

billmock-app-rs's Issues

No more `i2c_polling_set_timeout` functions

Latest embassy-rs support i2c wait with duration instead of function call.
embassy-rs/embassy@cd12c9c
embassy-rs/embassy#2033

This is I wanted and need to patch to cover the changes.

Manual book with mdbook

Create manual book with https://rust-lang.github.io/mdBook/
Now application logic and concept is almost fixed. Thus it's time to write document for the product.

Implement `StartButtonDecideSerialToVend` Logic

Description

According to AppMode0v3 DIP switch settings specifications, only BypassStart and BypassJam enumerations are currently implemented. However, the implementation of StartButtonDecideSerialToVend is required now. (BypassJamAndExtraSerialPayment has been partially implemented, but enabling USART1 and driver improvement are needed, resulting in development being postponed.)

StartButtonDecideSerialToVend

When payment serial communication is received from the credit card reader, the vend signal is not immediately transmitted to the host side's vend output. Instead, on the vend side, when a start input signal is received, the corresponding Player's host side is determined (whether Player 1 or Player 2), and the vend signal is then transmitted.

Re-write eeprom page every 1 minute

Fix incorrect uptime field by starving event. Instead re-write EEPROM page periodically

Separate BillMock HW 0.3 and 0.4 configuration

Description

Current HW 0.3 has following critical issue

• START/JAM on Vend Side Player 1 has been not routed : This should be hand-wired for use
• Inhibit Input on Host Side Player 1/2 has floated state: Just disable EXTI initialization on board boot state.

New HW 0.4

• fixed both issue

Additional old 0.2

• Disable Inhibit input 1/2 both as 0.3 need

By above of requirement and consideration, separate feature and board config.

Support new remote cash receipt feature

Description

New ED785 support cash receipt feature.
Support feature protocol and logic

[EPIC] app 0.3.0 milestone

Goal

• OTP for mass-production and Serial-Number for display on ARM-DAP or card-terminal (#33)
• DisplayHwInfo impl and activate when release from DisplayRom state (#36)
• 0.5 mini version hardware support and show DisplayRom on LCD when new tactile switch clicked. ( #38 )
• MPtool and dummy elf header for mass production ( #40 )
• Fix incorrect uptime field by starving event. Instead re-write EEPROM page periodically ( #43 )
• Enhance business logic ( #45 )

Postponed goal

• PushSaleSlotInfoPartialInhibit impl and retouch sale slot inhibition by INH signal or DIP_SWITCH.

0.5 mini hardware support

BillMock-HW 0.5 Mini have extra tactile switch nearby DIP switch.
This button is added for displaying CoinCount and Card Count easily

• Add board support for 0.5 mini
• README.md and mdbook update
• Bind to actual logic

Enhance business logic

Current business logic is glued stuff from 0.1.x.

Enhance the logic code considering changes from 0.2.x

Simple implement for DIP Switch `InhibitOverride` and `TimingOverride`

Description

The current code includes enum type definitions for InhibitOverride and TimingOverride, but the actual functionality is not implemented. It also lacks consideration for RS232 credit card payment (commented out expected line.). Please proceed to incorporate the functionality for I/O operations.

[EPIC] app 0.2.0 milestone

Goal

• Support text display to credit card reader LCD and external display with optional serial port
• DIP Switch (App Mode) 0b11 is BypassJamAndDisplayRom #23
• Store total coin clock count and clock count(or price) from credit card reader.
• External EEPROM (8Kbit or 16Kbit) ( #22 )
• Support 0.4 and 0.4 mini ( #26 )
• Deprecate 0.2, 0.3 HW from 0.2.x

Add DisplayRomMethod ,TidRead for `serial-arcade-pay` and `example`

Description

Some credit card readers have the capability to display text on an LCD screen.

To show information such as credit/coin counts from EEPROM and a shorten program git hash, there is a need for an improvement in the serial-arcade-pay method

Additionally, a method for reading the TID (Terminal ID) is required to display terminal information.

example :

5fe222c-d TID:   xxxxxxx
Card:123456+234567=580245
Coin:345678+456789=802467
1P: 469134, 2P: 691356

• deadbeef-d , -d is git is dirty, if there's no -d it's clean git commit

pin-map support for `0.4` and `Mini-0.4` hardware

https://github.com/pmnxis/BillMock-HW-RELEASE#v-04-2023-09-08
https://github.com/pmnxis/BillMock-HW-RELEASE#v-04-mini-2023-09-12

0.4 and Mini-0.4 hardware has different GPIO usage versus 0.3/0.2.

In this ticket doesn't include SPI-pin-out

• src/boards/billmock_0v4.rs
• src/boards/billmock_mini_0v4.rs

Redesign `BufferedOpenDrainRequest` for taking custom timing from `Alt~`

Description

The current BufferedOpenDrainRequest enum contains AltForever and AltTickTock, both of which only receive the signal_count, while the duration of the open drain pulse signal is controlled by the statically shared DualPoleToggleTiming struct's alt: ToggleTiming.
However, due to a request from the credit card payment method, there is a temporary need to modify the signal duration. To accommodate this, the structure will be changed within the request queue to utilize a single element for the Alt~ series enum. This element will include the duration value as a constrained bitfield.

This issue involve updating the BufferedOpenDrainRequest type, making alterations to dependent compressed Raw (u16 based) serdes code, incorporating adjustments to the BufferedOpenDrain implementation, and removing the no longer needed pub alt: ToggleTiming field from DualPoleToggleTiming.

Footprint of RawBufferedOpenDrainRequest that reduced to u16

#### AltTickTock
 15  14  13  12  11  10   9   8   7   6   5   4   3   2   1   0
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|Alt|T/F|  signal_count |      off_time     |      on_time      |
| 1 | 0 |               |      duration     |      duration     |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

#### AltForever
 15  14  13  12  11  10   9   8   7   6   5   4   3   2   1   0
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|Alt|T/F|     off_time duration     |      on_time duration     |
| 1 | 1 |                           |                           |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

#### Others
 15  14  13  12  11  10   9   8   7   6   5   4   3   2   1   0
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|Alt|T/F|   other enumeration   |          internal u8          |
| 0 | 1 |                       |                               |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

Definition of done

• AltForeverandAltTickTock` redesign
• Serdes for RawBufferedOpenDrainRequest <-> BufferedOpenDrainRequest
• Fix BufferedOpenDrainRequest module implementation
• Remove unused variable or define such as DualPoleToggleTiming and alt: ToggleTiming

Reduce `.text` size to fit `STM32G030C6T6` (Flash 32KiB)

With NDA serial payment library, 34724 Bytes filled in flash area. Current STM32G030C8T6 allow up to 64KiBs, but future BOM there's some possibility to reduce to 32KiBs using STM32G030C6T6.

Refactoring the code to reduce binary size and speed-up

Blink when output vend signal

Blinking two LEDs separately in response to the Vend Toggle signal for Player 1 and Player 2.

`DisplayHwInfo` impl and activate when release from DisplayRom state

To see serial number with LCD display, send display command when DisplayRom state is released

EEPROM factory reset by SVC button

Long press SVC button in 0v5 series board, reset play counts in EEPROM

fingerprint for mptool on ELF dummy section

When read .rodata with objdump.
The result comes with human readable but hard to parsing git hash and version with code.

 8009cb0 2d2d2d2d 2d2d2d2d 2d2d2d2d 2b62696c  ------------+bil
 8009cc0 6c6d6f63 6b2d6170 702d7273 302e322e  lmock-app-rs0.2.
 8009cd0 31306361 32623465 36663533 34633631  10ca2b4e6f534c61
 8009ce0 65393738 36666532 37626338 37643935  e9786fe27bc87d95
 8009cf0 63303534 31336537 34323032 332d3130  c05413e742023-10
 8009d00 2d323720 31353a35 323a3232 202b3039  -27 15:52:22 +09
 8009d10 30303063 61326234 6520206e 6f742069  000ca2b4e  not i
 8009d20 6d706c65 6d656e74 65647372 632f636f  mplementedsrc/co
 8009d30 6d706f6e 656e7473 2f736572 69616c5f  mponents/serial_

Make more convenient parsing for mptool, make wrapped dummy section for containing firmware version, git hash, any other related things.

Basic I2C EEPROM Support

Consider #21 0.2.0 milestone,
Prepare I2C EEPROM support for 0.4 (2023-09-08) HW.

Implement Mutual Inhibit module and use

Mutual Interaction Management Module for the Inhibit feature is required to oversee two separate input sources(DIPSW override and host-side signals).
This module is responsible for controlling two specific outputs on the Vendor Side and two outputs for the Credit Card Terminal (RS232). Particularly, for devices like the Credit Card Terminal, signals should only be sent when there are changes (minimizing the number of output occurrences).

Indicate card terminal version and warn to LCD display

Utilize TerminalVersion enum, indicate card terminal version then alert to display

Serial Number on OTP flash area.

The board should have unique serial number for each board.
Data structure is ASCII 12bytes that is [u8;12]

Definition of done

• Limit normal program bytes to 62KiB from 64KiB
• Test program to write 12byte + hash (4bytes) on MCU flash side. (OTP)
• Validation for several situation (overwrite new firmware, lock->unlock cause erasing last page .. etc)
• Bind to CardTerminalTxCmd::ResponseDeviceInfo

NACK/ACK support for SerialPayment device

Current module don't have interface for output NACK/ACK signal to device.
Interface and glue implementation is required for serial device and application.

Definition of done

• NDA / Open serial port driver, interface implementation
• Glue on current serial payment application logic
• Test with actual device (NDA)

[EPIC] app 0.3.1 milestone

Goal

• Factory Reset EEPROM (coin/credit count only and whole area) by SVC button (0.5 series hardware only) ( #49 )
• Indicate NDA crate is enabled in MP tool, and MP fingerprint ( #48 )
• Indicate card terminal version and warn to display ( #51 )
• Up to date document ( 06fb086 )

Implement Busy signal usage

The "Busy" output signal remains active low from the moment a payment signal is received from the credit card or when the VEND input signal goes active low until the VEND output signal toggles and completes.

Sample timing sequence

┌───────────────────────────────────────────┐
│ BUSY                                      │
│ Output Sequence                           │
└───────────────────────────────────────────┘

┌─────────┐
│ Credit  │
│ Payment │
└─────────┘

 ┌───────────────┐      ┌─────────────────┐
 │ VEND          │      │ VEND            │
 │ Input         │      │ Output          │
 └───────────────┘      └─────────────────┘

Eeprom Novella refactoring and move codes to extern repo

Eeprom Novella refactoring and move codes to https://github.com/pmnxis/novella