Ford Connect Simulator

Are you a developer writing code for the FordConnect API? If so, this simulator helps validate your scenarios. Simulate both ICE and EV vehicles, open doors, lock, start, empty fuel tank, etc.

Comment

Inspiration

I entered the FordConnect hackathon and realized that since I don't own a EV Ford I couldn't test all of my scenarios. The test VIN provided was for a ICE (internal combustion engine) and that also lacks things you likely want to try like, empty the gas tank, open the driver door, forget to lock the doors, etc.

What it does

This simulator returns the same JSON responses as the FordConnect API, for both EV and ICE vehicles. Thanks to Scott Tate in the forums for providing sample EV JSON responses and answering all of my technical questions.

The simulator has a vehicles.js file where you configure your simulated vehicle. It also exposes a bunch of /sim routes for changing the state of the vehicle, allowing you to easily test various scenarios. For example, if you POST /sim/fuel/:vehicleId?level=100.0&dte=700.0 then you will have a full tank of gas returned the next time your app calls /api/fordconnect/vehicles/v1/{{vehicleId}} vehicle.vehicleDetails.fuelLevel; but you can call POST /sim/fuel/:vehicleId?level=-2.0&dte=0.0 and you will be running on fumes for your vehicle.vehicleDetails.fuelLevel.

There are alternatives to the simulator, like mocking responses in your app, using a web proxy to edit traffic, etc. but hopefully people will find this API solution intuitive to use. It has a detailed README.md file, a documented app.js file and test cases that help describe all of the potential API responses you could expect (e.g. expired token, expired commandId, etc.)

For my own projects, I used the simulator and found it very helpful to quickly run a POSTMAN command to change the state of the vehicle to the next scenario I was testing.

It also uses the FordConnect API to clone your existing vehicles, allowing you to clone your ICE or EV vehicle state and then make quick modifications like 50% battery or have the alarm go off in the virtual world, so you don't annoy your neighbors during your midnight coding sessions.

Route Comment
/sim Returns the simulator's data in JSON representing all of the vehicles.
/sim/html Returns an HTML page with summary of the active vehicles.
/sim/clone Clones the vehicles in a FordPass account. Uses the real FordConnect API provided by Ford
/sim/today Set the simulator's today value (used for determining the next departure time.)
/sim/psi/:vehicleId Sets the tirePressureWarning on a vehicle.
/sim/modem/:vehicleId Sets the modem on a vehicle.
/sim/deepsleep/:vehicleId Sets the deep sleep for the vehicle.
/sim/firmware/:vehicleId Sets the firmwareUpgradeInProgess on a vehicle.
/sim/plug/:vehicleId Sets the plug status on an EV vehicle.
/sim/ignition/:vehicleId Sets the ignition status on the vehicle.
/sim/fuel/:vehicleId Sets the fuel level on an ICE vehicle. "level" is a percentage, "dte" (distance to empty) is in km not miles.
/sim/battery/:vehicleId Sets the battery level on an EV vehicle. "level" is a percentage, "dte" (distance to empty) is in km not miles.
/sim/location/:vehicleId Sets the location of a vehicle. You can optionally specify a speed and direction (like NorthWest).
/sim/door/:vehicleId Opens or closes a door on the vehicle.
/sim/alarm/:vehicleId Sets the alarm for the vehicle.

How we built it

The simulator is built with Node.js and using Express for the routing. Mocha and Chai are used for the tests, which put the simulator in a specific state and validate the responses. The tests were written by looking at Postman data against to FordConnect API to understand the HTTP status codes, JSON body and critical HTTP headers that are returned. For scenarios where the test VIN provided by Ford didn't give enough data, I asked questions in the Slack forums and Scott Tate helped track down answers.

The readme was written using markdown.

Challenges we ran into

The FordConnect API only returns data for our test ICE vehicle, so it was difficult to determine what the responses should be for an EV vehicle. The API itself has some inconsistencies and this project tries to emulate that behavior, so attention to detail needed to be higher than a typical project.

Accomplishments that we're proud of

My goal was to have an API that everyone could use within one week of starting the project. I met that goal and released a 15-minute video on Friday night.

Other people found my \FordConnect folder useful for understanding how to communicate with the FordConnect API from a NodeJS project & one person is using it for their project.

I continued to harden the project and added test cases, which helped identify issues. I feel comfortable having someone look at the repo, as I feel the quality of the code is decent.

What we learned

I learned a lot about testing with Mocha and Chai and how easy it is to use Express.

What's next for Ford Connect Simulator

I was learning as I went along, knowing what I know now, I'd plan on refactoring a lot of the code. There are existing libraries out there that do some of the work I did, so I'd also like to refactor to leverage their work.

I've never created an NPM package before, so I'd like to learn how to do that. Moving my FordConnect helper library into an NPM package would be helpful for code reuse. I ended up copying the files into my other projects for now.

Built With

Share this project:

Updates

posted an update —

Our internet went down and we lost power in high winds today. I added high level monitoring to make sure the simulator is running and I moved my Node JS code onto a VM in Azure instead of hosting it in my garage.

I highly recommend you host it yourself for the best experience, like cloning your existing FordPass account using post 3000. I put together a bunch of getting started videos if you prefer watching videos over reading documentation. If anything is unclear, post a message here or on YouTube and I'll edit the video.

Log in or sign up for Devpost to join the conversation.