OVMS Open Vehicle Monitoring System Model: OVMS-31-5360A www.openvehicles.com OVMS Advanced User Guide v3.2.0 (18th January 2019) For OVMS Hardware Module v3.1 and Firmware v3.2.
History Version Date Who Summary v3.1.0 15th March 2018 Mark WebbJohnson Initial version written v3.1.1 6th August 2018 Robert Sharpe Simplified terminology/layout to make easier to read/use Identified potential TODOs Added vehicle commands section Created standard, vehicle specific template v3.2.0 18th January 2019 Mark WebbJohnson Document javascript functionality for v3.2.
Auto Start Configuration 17 Networking Options 18 1. Wifi Client 19 2. Wifi Access Point 19 3. Cellular Data 19 Firmware Update 20 Flash from Web 20 Flash from File 20 12V Calibration 21 Module Configuration 22 Cell phone App Configuration 22 Advanced Console Usage 23 Console Connections 23 USB Console 23 SSH Console 24 Console Basics 26 Logging 27 Logging to the console 28 Logging to SD CARD 29 Logging configuration [3.1.
OvmsLocation 50 OvmsMetrics 50 OvmsVehicle 50 Module Factory Reset 52 Module Factory Firmware 54 Install esptool.
30 kwh models 62 Custom Metrics 62 Custom Commands 62 Range Calculation: 63 O2 OBDII 64 RT Renault Twizy 65 Configuration 65 Custom Metrics 65 Custom Commands 65 TR Tesla Roadster 66 Hardware Requirements 66 Module Installation in the vehicle 66 Antenna Installation 67 Antenna beside rear passenger headrest 67 Antenna on windshield/windscreen 68 Configuration Options 68 Tesla Roadster Notes 69 Thanks 69 TS Tesla Model S 70 Configuration 70 Custom Metrics 70 Custom C
Appendices Appendix 1: OVMS Metrics Table OVMS v3 User Guide 79 79 Page 6 / 86
Welcome The OVMS (Open Vehicle Monitoring System) team is a group of enthusiasts who are developing a means to remotely communicate with our cars, and are having fun while doing it. The OVMS module is a low-cost hardware device that you install in your car simply by installing a SIM card, connecting the module to your car’s Diagnostic port connector, and optionally positioning a cellular antenna. Once connected, the OVMS module enables remote control and monitoring of your car.
Warning! OVMS is a hobbyist project, not a commercial product. It was designed by enthusiasts for enthusiasts. Installation and use of this module requires some technical knowledge, and if you don't have that we recommend you contact other users in your area to ask for assistance. The OVMS module is continuously powered by the car, even when the car is off.
OVMS System Components The OVMS Module The OVMS v3 module is housed in a plastic enclosure; held secure by four small screws. Once open, you can see the main OVMS v3 motherboard, and an optional modem board. At one end of the module is the main DB9 connector you will use to connect to the vehicle, as well as GSM (cellular) and GPS (positioning) antenna connections. At the other end of the module is the DA26 expansion connector, the USB diagnostic connector, and a Micro SD card slot.
Cellular Modem Option and GSM Antenna The cellular modem option allows you to control your vehicle when out of wifi coverage range. The majority of OVMS users choose this option, and you will require it if you want to monitor your vehicle when away from home or office. Each OVMS modem module is provided with a Hologram SIM card pre-installed. This low cost service allows you to get cellular connectivity simply. It also allows you to roam between countries without worry.
compatibility with existing OVMS v2 cellphone apps and servers, OVMS v3 includes full support for the OVMS v2 protocol. OVMS Server v3 The OVMS Server v3 protocol is MQTT. This is an industry standard protocol, and means an OVMS v3 module can communicate with any standard MQTT server. While this is the future of OVMS, support for this is experimental at the moment and production users should use OVMS Server v2 protocol.
Installation Pre-Installation Steps Warning! Prior to connecting the OVMS module to the vehicle, or computer via USB, if you have the GSM cellular option we recommend you connect a GSM antenna. GSM systems are designed to always operate with an antenna, and powering on one without could damage the equipment. Prior to installation, please make sure you have the following available: 1. 2. 3. 4. 5. 6. 7. The OVMS v3 module in it’s enclosure. A small screwdriver, for opening the module (if necessary).
modules). The server itself will also have a specific hostname and port it uses for OVMS protocol v2 communications. Hologram Activation OVMS has partnered with Hologram and is providing a Hologram SIM pre-installed in every OVMS modem board. In addition, Hologram have provided our community a coupon code valid for US$5 off data usage: Hologram Coupon Code: OVMS When activating your Hologram SIM, you’ll need to enter the ICCID written on the SIM itself.
Initial Connection (Wifi and Browser) From the factory, or after a factory reset, your OVMS module will be running an access point, with the following credentials: SSID: Password: OVMS OVMSinit As this is insecure, you should take care not to leave the module running unconfigured. Using your laptop/tablet/phone, establish a wifi connection to the module. You should see an IP address in the range 192.168.4.x allocated, with a gateway at 192.168.4.1.
Setup wizard The first thing to do is run the setup wizard. Click “Start setup now”. The wizard takes you through the initial setup in five simple steps, telling you what it is doing and what to expect for each step. The wizard will need to reconfigure the module for the Wifi setup, read the notes and be prepared to reconnect to the module as necessary. Note: we recommend not to use a password manager during the setup process. Some browsers, e.g.
The wizard should be able to restore access after problems occurring in the process. As a last resort if it fails to recover at some point, you can always do a factory reset and start over again. Manual configuration After finishing the wizard or if you prefer to do a manual setup, the configuration menus will provide single pages for each module function. These also contain advanced options for the features, so it’s worth having a look.
You should enter the server host (api.openvehicles.com, or ovms.dexters-web.de, usually), and vehicle password (aka ‘server password’ - as entered on the server when you registered your vehicle). The Vehicle ID field should already be there, and the other parameters are optional. Auto Start Configuration OVMS has a powerful scripting language that can be used for complex configurations, but to get started it is simplest to use the Auto Start system.
You will usually want to click to “Enable auto start”, and “Start server v2”. The other fields should have been populated correctly automatically for you. If you are using the optional modem module, you should also click “Start modem” to enable the modem. Once complete, you can “Save & reboot” to activate your new configuration. Warning: Do not set the Wifi mode to “AP+Client” or “Client” before having configured your Wifi network.
1. Wifi Client OVMS can connect to a WiFi Access Point, using standard WiFi (802.11 b/g/n) protocols. To connect the SSID (Access Point name) and associated password. In simple client mode, you can connect either to a specific SSID. Alternatively, you can use a scanning client mode to connect to any known WiFi Access Point when within range (note, however, that this is not possible when you run both client and access point on the same OVMS device). 2.
Firmware Update The factory firmware that is provided with the module may be quite out of date. You should perform a firmware update to ensure that you have the latest firmware. You can do this either over Wifi client connections, or via an SD CARD. We recommend using the auto update system. This will be preconfigured if you have used the setup wizard. The automatic updates are done within a selectable hour of day, and only if Wifi connectivity is available at the time.
12V Calibration The 12V voltage is measured using the incoming voltage that powers the OVMS. You can calibrate it using… config set system.adc factor12v The has to be calculated using: oldFactor * (displayedVoltage / actualVoltage). ● ● ● oldFactor is the old value set. If you have not changed it yet it is 195.7 displayedVoltage is the Voltage as displayed by the OVMS. actualVoltage is the Voltage as measured by hand using a voltmeter.
v.b.12v.voltage.ref v.b.12v.voltage.alert v.e.charging12v 12.51V no yes Reference voltage of the fully charged & calmed down 12V battery If the 12V critical alert is active (yes/no).
Advanced Console Usage Console Connections OVMS v3 includes a full command line console that can be accessed in various ways: 1. Using a micro USB cable to a host computer. If the OVMS is not recognised via USB download the driver from SILABS website). You will also need a suitable terminal emulator. The baud rate is 115200, and you should not enable hardware flow control. 2. TELNET (over wifi).
USB Console Our recommendations for the USB console are as follows: 1. You can use a Windows, Linux, a Mac OSX workstation or an Android device with a USB OTG adapter cable. 2. If your operating system does not have the SILABS USB driver, you can download from SILABS website. Linux note: if your distribution includes the braille display driver “brltty”, you may need to uninstall that, as it claims any CP2102 device to be a braille device. This applies e.g. to openSuSE 15.0. 3.
SSH Console A workstation (Mac, Linux, Window), on the same wifi network as the OVMS module, can use the ssh protocol to connect. In Windows you can use the free PUTTY ssh client. In Linux and OSX ssh is built-in. The syntax is simply: ssh user@ip Where ‘user’ is the username (normally ‘ovms’) and ‘ip’ is the IP address of the OVMS v3 module. In environments supporting mDNS networking, you should also be able to connect using the mDNS name < vehicleid>.local.
Console Basics Let’s use SSH to demonstrate this: $ ssh ovms@ovms.local Welcome to the Open Vehicle Monitoring System (OVMS) - SSH Console Firmware: 3.1.003-2-g7ea18b4-dirty/factory/main Hardware: OVMS WIFI BLE BT cores=2 rev=ESP32/1 OVMS# When first connecting using USB, the console will be in non-secure mode (as indicated by the “OVMS>” prompt). Here, only a limited number of commands are available (such as viewing network status, modem status, or system time).
log metrics module network notify obdii ota power re script sd server simcom stat store test time unlock unvalet valet vehicle vfs wakeup wifi LOG framework METRICS framework MODULE framework NETWORK framework NOTIFICATION framework OBDII framework OTA framework Power control RE framework Run a script SD CARD framework OVMS Server Connection framework SIMCOM framework Show vehicle status STORE framework Test framework TIME framework Unlock vehicle Deactivate valet mode Activate valet mode Vehicle framework
Logging Logging to the console Components of the OVMS system output diagnostic logs (information, warnings, etc). You can choose to display these logs on your connected console with the ‘log monitor yes/no’ command: OVMS# log monitor ? Usage: log monitor [no|yes] no Don't monitor log yes Monitor log By default, the async (USB) console will have log monitoring ‘yes’, but the others ‘no’. Note: the web shell does not support log monitoring yet.
Logging to SD CARD You can also choose to store logs on SD CARD. This is very useful to capture debugging information for the developers, as the log will show what happened before a crash or misbehaviour. We recommend creating a directory to store logs, i.e.: OVMS# vfs mkdir /sd/logs To enable logging to a file, issue for example: OVMS# log file /sd/logs/20180420.log The destination file can be changed any time. To disable logging to the file, issue “log file” without a file name or “log close”.
Logging configuration [3.1.005] Use the web UI or config command to configure your log levels and file setup to be applied automatically on boot. OVMS# config list log log (readable writeable) file.enable: yes file.maxsize: 1024 file.path: /sd/logs/log level: info level.simcom: info level.v-twizy: verbose level.
The “log” command can be used for temporary changes, if you change the configuration, it will be applied as a whole, replacing your temporary setup. If a maximum file size >0 is configured, the file will be closed and archived when the size is reached. The archive name consists of the log file name with added suffix of the timestamp, i.e. “/sd/logs/log.20180421-140356”. Using a logs directory will keep all your archived logs accessible at one place.
Virtual File System OVMS includes a Virtual File System (VFS) used to unify all storage in the system. The primary configuration and scripting storage is mounted as ‘/store’, and the SD card as ‘/sd’.
Over the Air Updates OVMS v3 includes 16MB flash storage. This is partition as: ● ● ● ● ● 4MB for factory application image (factory) 4MB for the first OTA application image (ota_0) 4MB for a second OTA application image (ota_1) 1MB for /store configuration and scripting storage The remainder for bootloader, generic non-volatile storage, and other data In general, the factory application firmware is stored in flash at the factory, during module production.
Firmware: 3.1.003-2-g7ea18b4-dirty/factory/main (build idf v3.1-dev-453-g0f978bcb Apr 7 2018 16:26:57) Server Available: 3.1.003 Running partition: factory Boot partition: ota_1 If the bootloader fails to boot from the specified OTA firmware, it will failover and boot from factory. We can flash firmware to OTA either from a file on VFS (normally /sd), or over the Internet (via http).
Boot Status & Crash Report OVMS maintains a record of the reason for each boot, in RAM that survives a reboot.
Configuration OVMS stores all it’s configuration in a standardised protected configuration area accessed by the ‘config’ command. The configurations are organised as follows: = For example: Parameter vehicle wifi.ssid auto Instance id MYSSID init Value OVMSBOX MyPassword yes Each parameter can be defined (by the component that owns it) as having readable and/or writeable attributes, and these act as access control for the parameters.
Metrics Metrics are at the heart of the OVMS v3 system. They are strongly typed named parameters, with values in specific units (and able to be automatically converted to other units). For example, a metric to record the motor temperature may be an integer in Celsius units, and may be convertible to Fahrenheit. The full list of metrics available can be shown: OVMS# metrics list m.freeram m.hardware m.monotonic ... v.p.latitude v.p.longitude v.p.odometer v.p.satcount v.p.speed v.p.trip v.tp.fl.p v.tp.fl.t v.
For developer use, there are also some other metric commands used to manually modify a metric’s value (for testing and simulation purposes), and trace changes: OVMS# metrics ? list set trace OVMS v3 User Guide Show all metrics Set the value of a metric METRIC trace framework Page 38 / 86
Time OVMS v3 User Guide Page 39 / 86
Geofenced Locations OVMS v3 User Guide Page 40 / 86
Events Internally, OVMS raises events whenever significant events occur. An event is simply a name, along with associated data. Individual vehicle types may also issue their own events, and custom user events are also possible. Here is the list of standard system events in the OVMS v3 firmware: Event Data Purpose sd.mounted The SD card is mounted and ready to use sd.unmounting The SD card is currently unmounting sd.unmounted The SD card has completed unmounting sd.
server.v3.waitnetwork V3 server connection is waiting for network server.v3.connectwait V3 server is pausing before connection server.v3.connecting V3 server connection in progress server.v3.authenticating V3 server connection is authenticating server.v3.connected V3 server connection established online server.v3.disconnected V3 server connection has been lost server.v3.waitreconnect V3 server is pausing before re-connection server.v3.stopped V3 server has been stopped vehicle.require.
vehicle.charge.12v.stop Vehicle 12V battery has stopped charging vehicle.locked Vehicle has been locked vehicle.unlocked Vehicle has been unlocked vehicle.valet.on Vehicle valet mode activated vehicle.valet.off Vehicle valet mode deactivated vehicle.headlights.on Vehicle headlights are on vehicle.headlights.off Vehicle headlights are off vehicle.alarm.on Vehicle alarm has been armed vehicle.alarm.off Vehicle alarm has been disarmed vehicle.charge.
system.modem.down Modem has been disconnected system.shuttingdown System is shutting down system.shutdown System has been shut down network.wifi.up WIFI network is up network.reconfigured Networking has been reconfigured network.up One or more networks are up network.interface.change Network interface change detected network.wifi.down WIFI network is down network.down All networks are down network.modem.up Modem network is up network.modem.down Modem network is down network.mgr.
Notifications OVMS v3 User Guide Page 45 / 86
Command Scripts Lists of commands can be entered into a script file and stored in the VFS for execution (in the /store/scripts directory). These are called ‘command scripts’ and are simple sequential lists of OVMS commands. A command script can be executed with: OVMS# .
