The making of MMM-HK-KMB module
EDIT: I created MMM-HK-Trasnsport-ETA module that uses DATA.GOV.HK and this is intended to replace this module.
In this story, I’d like to discuss the reverse engineering method of my MMM-HK-KMB MagicMirror² module.
Background
It is time-wasting waiting for your bus at the bus stop when you actually can find the ETA (estimated arrival time) in the KMB application. However, finding the ETA by unlocking the phone, opening the KMB app, and find my ETA would be very cumbersome. Why not show all this info on the TV screen? Then later on I read an article about MagicMirror².
Isn’t it nice to know the right time before I leave home?
Reverse Engineering (Part 1)
EDIT: Packet Capture is not working on Android 9+ device. Please use HTTP Toolkit.
Then I tried to find the API that is useful for me. Therefore I installed the Packet Capture Android Tool and sniff the traffic between the phone app and the server. After learning how to use the Android Tool following this nice tutorial. Following the guide, I open Packet Capture, Open KMB App, read the ETA from the app, and then collect the full URL. Luckily I could find some useful API:
The first section is the API and the third part is the response collected from the server. And here is a sample URL call:
http://etav3.kmb.hk/?action=geteta&lang=tc&route=3D&bound=2&stop=KW16-W-1950-0&stop_seq=4And this is the visualized response format:
It is clear that the ETA is on the response t of each response.
Then I created the first version of MMM-HK-KMB module using the full URL. The module just simply reads the list of prepared API from the configuration file, fetch the response from the server and then display the result on the screen.
Reverse Engineering (Part 2)
Unlike the phone, every “mirror” is stayed in one physical location, and therefore it would make more sense if the mirror shows the ETA of the bus stop nearby. Instead of getting all the URLs, why I shouldn’t use stopID — the unique ID of a bus stop?
Thus I reviewed the ETA API inputs and try to understand how to use the API. And here are the 4 parameters required:
- route — The route number
- bound — The direction
- stop — The ID of the stop, which represent the physical location of the bus stop
- stop_seq — The sequence of the stop
Next, I tried to obtain the needed information from the web version (link). Then I open Chrome Developer Tools (tutorial) and click around the web, and see if I am lucky enough to capture something meaningful.
Here are the APIs obtained from the official web site:
Thus, I have all the information to generate the ETA parameters. Here are the sequence:
- 2ⁿᵈ API: Get the routes from a stop (using stop ID)
http://search.kmb.hk/KMBWebSite/Function/FunctionRequest.ashx?action=getRoutesInStop&bsiCode=SL01-S-1050-0
- 3ʳᵈ API: For each route, obtain the bus bounds of a bus route
http://search.kmb.hk/KMBWebSite/Function/FunctionRequest.ashx?action=getroutebound&route=71B
- 4ᵗʰ API: Call the API with all the bounds, then we can obtain all the stops traveled by the bus route (including BSICode, which is the stop ID)
http://search.kmb.hk/KMBWebSite/Function/FunctionRequest.ashx?action=getstops&route=71B&bound=1
For each routeStop component, it not only contains the BSIcode (stop ID), but also the route, bound, stop, and seq (stop sequence) needed by the ETA API.
Based on the above API calls, I would have sufficient information to build my second version of the MMM-HK-KMB module.
Conclusion
First of all, this article highlights the reverse engineering method using network sniffing tools to find out the API call in Android and Chrome browser.
This skill is essentially useful in the black box world, where API documentation is not open to the public. Once you have all the information (via API) needed then you would have sufficient information to build the Web Page/APP.
If you are interested in displaying the KMB ETA info on your screen, please feel free to take a look at my MagicMirror² module.
