An OSC timer app that can optionally unlock a bluetooth lock that uses the ESmartLock phone app.
A simple use case might be throwing regular keys into a lockbox secured by the bluetooth lock.
⚠ Keep in mind bluetooth can be unreliable. BE SAFE ⚠
[[TOC]]
OSCLock's parameters & timings are fully configurable.
Check down in the config section or the config.toml file.
- Starts a timer for a specified duration.
- While the timer is running, unlock functions of the app are disabled.
- Specific avatar parameters that can add or remove some time
- Will readout a parameter so you can reflect the current timer on your avatar.
- By default, unlock functions of the app are disabled
- When a specific parameter is recieved, the app will enable unlock functions.
- Unlock functionality is always available. Good for testing your lock.
- TBD
Although the app is built for An ESmartLock in mind, it doesn't actually require one to function. If you'd like to entirely skip over the physical device and just use it's timer control functions and readouts, feel free to skip 3-8 in setup.
Tables containing information on all available settings you can change in the config.toml files.
Click a > to expand the section.
Main Settings
| Value | Info | Default |
|---|---|---|
| OSCQuery | Enable OSCQuery (IP & Listening port will be ignored) | false |
| ip | Address to send OSC data to | "127.0.0.1" |
| listener_port | Port to listen for OSC data on | 9001 |
| write_port | Port to send OSC data to | 9000 |
| mode | Testing, Basic, Or Timer | "Timer" |
| debugging | Extra console readouts, mainly for OSC debugging | false |
| lock_type | Not used yet, maybe for different bluetooth locks later. | ESmartLock |
| esmart_username | Account username for login | "" |
| esmart_password | Account password for login | "" |
| device_password | Lock passcode will be written here after a successful login | "" |
Timer Settings
| Value | Info | Default |
|---|---|---|
| max | Maximum time. How much sand can the hourglass hold at a time? | 60 |
| absolute_min | Time will be added if it total time is below this. 0 disables. | 0 |
| absolute_max | If overall time reaches this, inc_step wont work. 0 disables. | 120 |
| starting_value | Time in minutes the timer should start at. Random if -1 | -1 |
| random_min | Random minimum time | 40 |
| random_min | Random maximum time | 60 |
| inc_parameter | When this Bool is true via OSC, it should increase the timer. | "" |
| inc_step | Time in seconds to add (int) | 60 |
| dec_parameter | When this Bool is true via OSC, it should decrease the timer. | "" |
| dec_step | Time in seconds to subtract (int) | 300 |
| input_cooldown | Minimum cooldown between allowed inputs. | 1500 |
| readout_mode | Method of translating time remaining via OSC. Chart below | 0 |
| readout_parameter | Readout parameter 1 | "" |
| readout_parameter2 | Readout parameter 2 (optional) | "" |
| cooldown_parameter | True while cooldown is active | "" |
| readout_interval | Time in miliseconds between parameter updates. | 500 |
Readout Modes
readout_mode determines how data is output from OSCLock.
Choose a method that works for you and your avatar.
P1 = readout_parameter and P2 = readout_parameter2
| readout_mode | Use of Readout parameters |
|---|---|
| 0 | No readout parameter will be used |
| 1 | P1, float 0 to +1 |
| 2 | P1, float -1 to +1 |
| 3 | P1, float -1 to +1 for minutes. P2, float -1 to +1 for seconds |
| 4 | P1, float -1 to +1 for minutes. P2, int 1:1 with seconds |
| 5 | P1 & P2, ints 1:1 minutes and seconds respectively |
| 6 | P1, int 1:1 mins/seconds. P2, bool determines min/sec data |
You can get the latest zip from releases (On the right side panel)
Unzip the entire folder wherever. You can also clone the git and build it yourself.
- Start OSCLock.exe once to generate a config.toml
- Exit the application and open the config.toml next to the executable
- Add your eSmartLock credentials to the config.toml
- Start OSCLock
- Unlock your lock (Press U)
- Once successfully completed, exit the application
- In the config.toml, device_password should now be filled in
- You can remove your esmart username and password if you'd like.
- Configure everything else in the confg.toml to your heart's content.
- HAVE A BACKUP PLAN AND BE SAFE. Bluetooth CAN'T BE TRUSTED.
Skip 3-8 if you don't actually have a physical lock
Avatar setup is decided by the user. You can use any of the readout modes to fit your avatar setup. A simple digital timer using readout mode 3 can be found on at https://zenithval.booth.pm/items/4892327
| Value | Info |
|---|---|
| H | Prints the help screen |
| T | Starts a new timer (If in timer mode) |
| S | Prints the status of the app and lock |
| U | Begins unlock process if available |
| Q | Quits the application |
| { | Encrypts the application config with a password |
| } | Decrypts the application config with a password |
Encryption
This uses very basic encryption to obfuscate the config.toml and timer files. After pressing { in the app, you'll be prompted to enter a password. If encryption is enabled, the timer can not simply be ended early by deleting the timer files. Decryption will force end the current time.
A fun way to use this might be encrypting the app with a code you don't remember and giving it to someone you trust. Goes without saying, only use this if you're confident and have confirmed it can open your lock and you're BEING SAFE.
It's hidden in the app interface but the { and } buttons still function.
- IT'S NOT. PLEASE exercise caution.
- Do not put the lock on anything that could put YOU in danger.
- Bluetooth is unreliable as heck. It'll drop randomly sometimes.
- Remember you can't open the lock without clicking the unlock button!
- You charged the lock, right?
- HAVE. A. BACKUP. PLAN.
Theoretically, this should work with ANY bleueooth Lock that uses the ESmartLock App.
Look for the white/green color laytout with the ESmartLock Icon. If a specific brand doesnt work please let us know.
- It's been well tested it with this lock.
- EseeSmart
- ELinkSmart
- Pothunder
- Dhiedas
- Reset OSC or delete the OSC folder at
C:\Users\(Username)\AppData\LocalLow\VRChat\VRChat - Did you include
/avatar/parameters/at the start? EG:/avatar/parameters/headpat_sensor - If your VRC parameter has spaces, replace the spaces with underscores, EG:
headpat_sensor
- Keep in mind VRchat synced Ints/Floats can only represent 128 values. (Only two accurate 2 decimal places on a -1 to +1 float)
- Readout mode 0 and 1 (0 to +1 or -1 to +1) are only good for reading out minutes. No seconds
- You'll need a second parameter for the seconds (other readout modes) or a special avatar setup to make pseudo seconds. IMO, not worth the pain.
The code as it is right now was only ever really meant to be a draft but we all know how that goes. At some point it'll probably be refactored, optimized, and, modularized to make it easier to add features.
Want to:
- The above.
- New Modes:
- Extensions of the basic timer mode.
- Some "Gamified" elements.
- Feel free to suggest.
- Automate a simple avatar setup.
- Unique avatar add ons/integrations.
- Support difficent brands of bluetooth locks. (VERY painful without an API, unlikely)
- Make the encryption feature not security theater. (Probably never, would be a safety hazard.)
- Prior programming before git history by @NeetCode 08/2022
- SharpOSC | MIT Liscense
- OSCQuery | MIT Liscense
- Tomlet | MIT Liscense
- FluentColorConsole | MIT Liscense
- App Heart Icon | Game-icons.net under CC by 3.0