Skip to content

Home

Jump to bottom Edit New page
Gordon Williams edited this page Oct 25, 2024 · 80 revisions

Welcome to the Bangle.js wiki!

Getting started

Bangle.js simple Getting Started information is available at:

There's also a video for getting started with Bangle.js 2:

Getting Started with Bangle.js 2

If you've read those and the FAQ on this page (below) and you're still having problems, please ask on the Bangle.js forum. Please do not ask question on KickStarter comments, YouTube comments, Twitter, or personal forum message to Gordon, etc as it's very hard to give useful, detailed responses.

Important Usage Information

  • Always unplug the charge cable after use. While the Bangle.js 2 cable is over-current protected, it could still attach itself and cause damage to other devices.
  • Do not force the charge cable onto the Bangle. If it is not magnetically attracted it's probably the wrong way around, and could cause damage to your Bangle.
  • There is a small voltage on the two middle contacts on the back of Bangle.js 2 (your Bangle should ship with some tape covering these). Without the tape, the voltage can in extreme cases cause corrosion of the contacts and even skin irritation - see here for more information.
  • While the Bangle.js 1 is IP68 water resistant (up to 10m underwater) the Bangle.js 2 is only IP67 water resistant (1m, 30 mins max in ideal lab conditions with cold water). This means the Bangle.js 2 should not be used for swimming, baths or even showers.

FAQ: Frequently asked questions

  • I can't turn my Bangle.js on! We ship Bangle.js turned off to comply with shipping regulations. To turn it on you need to hold the button for around 2 seconds.
    • Release the button as soon as you see the screen go white - holding the button for too long will put the watch in bootloader (DFU) mode and you'll need to hold the button down again to exit it.
    • The button is tactile - when pressing you should feel a 'click' - if you don't it may be because you're not pressing hard enough.
    • If the Bangle does not turn on, please leave it connected to a USB charger for 2 hours and try again (when the Bangle is off there is no notification onscreen about when it is charging or not)
  • How do I set the time? You can do so from the Settings app on the watch (see below about using the menus) but we'd recommend just going to the the App Loader website. If the watch time hasn't been set, when you connect the time and timezone will automatically be set up to that of your Web Browser. You can force it later using Set Bangle.js time in the More... tab.
  • I could connect to my Bangle, but now I can't - what's up? Bangle.js can only have one Bluetooth connection at a time.
    • Are you still connected to the Bangle from another PC/Phone? Gadgetbridge on Android as well as iOS ANCS will keep a connection open which will stop you connecting from other devices until you manually disable it.
    • Did you connect to the Bangle from your OS's Bluetooth menu? (Android, iOS, MacOS, Windows, etc) If so, try 'unpairing' and then try connecting again but from the App Loader.
    • Make sure that Settings -> Bluetooth -> BLE and Settings -> Bluetooth -> Programmable are switched to "On".
    • By default, Gadgetbridge's has Ignore Paired Devices set to true in Bluetooth settings so won't show previously paired devices
    • Has your Bangle somehow got stuck so you can't change settings? Eg. you disabled Bluetooth and removed the Settings app? Hold the button down for ~10s to reboot fully and enter the recovery menu where Bluetooth will be activated: https://www.espruino.com/Bangle.js2#recovery-menu
  • What features are currently implemented/available See this page
  • How can I find documentation on apps? Pretty much all apps have their documentation in the App Loader. Find the app and click Read more... under the description. For instance here is the documentation for the Settings app
  • How do I get back to the clock? Long-pressing the one button will always take you back to the default clock app, or if there is a red back-arrow in the top-left corner of the screen, that (or the button) can often be tapped to go back.
  • Why does my Bangle keep showing the original clock when I installed a new one? This is because of the default clock you've configured. Either delete all other clocks, or just go to Settings -> System -> Clock to choose a new default clock.
  • Why isn't the touchscreen responding? The touchscreen is only active when the lock symbol isn't displayed in the top left hand corner. Unlocking can be configured in several ways but the easiest is just to press the button. If you've removed the lock widget app, the lock icon won't show.
  • It's hard to press the right place with the touchscreen Try Settings -> System -> LCD -> Calibrate - this will ask you to press on a few distinct areas and will then work out the best calibration to use to ensure your presses are reported in the right place.
  • How do I open apps? When viewing the clock wake the watch if necessary (with a button press) then short press the button once to go to the launcher. In the default launcher, drag the screen to scroll, and tap the icon you want to launch
  • Why does my backlight keep turning on? By default Bangle.js has a 'wake on twist' feature enabled that can sometimes register a twist when there isn't one. This can be turned off from Settings -> System -> LCD -> Wake on Twist
  • How do I select from menus? In text menus, drag your finger up and down to change the selected entry, and then tap on the menu item to select (When Bangle.js 2 launched, this behaviour was different).
  • What are the letters in the top right of the screen? These are from the Bluetooth ID Widget. If you have more than one Bangle then you can use these to differentiate them when connecting via Bluetooth. If you don't want it, go to the App Loader, connect, go to My Apps, and uninstall it.
  • How do I update the watch's firmware? The apps can be updated just by clicking Update in My Apps in the App Loader, but the watch firmware itself needs to be updated using these instructions: https://www.espruino.com/Bangle.js2#firmware-updates
  • How do I assemble the wooden Bangle.js 2 Charge Cradle? It's not immediately obvious so there is a video at https://youtu.be/M1T2oitL85I
  • How do I get notifications on Android? You install the Android app on Bangle.js, and then the Gadgetbridge app on your phone.
  • How do I get notifications on iOS? You install the iOS app on Bangle.js, and then simply pair the phone with your iOS device
  • How do I use the App Loader from iOS? You need to install a Web Bluetooth browser for iOS (see the list below) as there isn't one built in. Once installed go to the App Loader at https://banglejs.com/apps from within the browser app you just installed. On iOS apps can't add Web Bluetooth functionality to Safari itself.
  • I am having trouble with the GPS See GPS Issues
  • My screen get shifted up with -> Bluetooth messages, my settings don't seem to be applying This is because your .boot0 file has got corrupted on the Bangle. It's a problem that can occur on some Bangle.js v2 with Bangle.js firmwares before 2.11. Make sure all your apps are up to date, then go to Settings -> Utils -> Rewrite Settings. This will fix the issue, however to stop it happening again you'll need to update your Bangle.js firmware
  • I'm only getting a few days battery life Here are some tips for getting maximum battery life, in no particular order:
    • Are you running an old firmware version? 2v23 and earlier in particular had problems on some watches, and upgrading to 2v24 would fix this.
    • Minimise the use of the GPS. If the GPS is left on it will drain the battery within 6 hours.
    • Minimise use of the heart rate monitor. Set heart rate monitoring to off or every 10 minutes in the Health app.
    • Set the LCD brightness to a lower value (for example 0.3)
    • Set the LCD timeout to 5 or 10 seconds
    • Turn off Settings -> System -> LCD -> Wake on Twist
    • Turn off Bluetooth (this has quite a low impact on battery life)
    • Use a clock that updates once per minute
    • Avoid flashing lots of apps to the storage, doing this several times a day will drain the battery.
  • The back of my Bangle looks scratched (where the heart rate monitor is) - the heart rate monitor comes with a protective covering which is a very soft plastic film and scratches easily. Please just remove it!
  • The Heart rate monitor isn't working well - check the last point - you may need to remove the protective film! The HRM currently doesn't work well when you are moving around, but if you don't move suddenly the heart rate monitor should pick your heart rate up in ~30 seconds.
  • My Bangle.js is running slow - First, ensure your Bangle.js firmware and apps are up to date - new firmwares have had big speed improvements. Otherwise:
    • this may be because the flash memory has got fragmented. Try going into the Settings menu, Utils, then Compact Storage. It may take a minute or two but should improve your Bangle's speed.
    • this could be because some apps you have installed are running in the background. You could always try uninstalling apps you think are at fault (or worst case do a Factory Reset and see how fast it is then). Or you can follow the steps at https://espruino.com/Bangle.js+Performance to see exactly which apps are causing slowdowns
  • Gadgetbridge can't see my Bangle.js - Gadgetbridge needs Location Access set to Always in Android in order to find Bluetooth devices properly (on some Android devices, it only gets set to While App is Running). If you go to Android Settings then Location access and App access to location then you can set Bangle.js Gadgetbridge as having access all the time.
  • Gadgetbridge keeps disconnecting from my Bangle.js - It may be that your phone is doing some 'battery usage optimisation' and deciding that Gadgetbridge should be shut down. See https://dontkillmyapp.com/ for device-specific advice on how to stop this happening.
  • All my measurements in °C, km, mph, my date is the wrong format - this is the default for Bangle.js. To change this, install the Languages App and set your country. After this, most apps should use the correct units.
  • I can't see non-english Characters in messages - by default Bangle.js only includes the ISO8859-1 character set which can render English and some European Languages.
    • On iOS you can install Fonts (all languages) (or whatever Fonts library covers your use case), and as long as Disable UTF8 is off in iOS settings (the default) then your messages should then be able to render.
    • On Gadgetbridge:
      • You can enable Text as Bitmaps to allow you to render any unknown characters (and emoji) on the phone: https://www.espruino.com/Gadgetbridge#extra-setup
      • You can install Fonts (all languages) (or whatever Fonts library covers your use case), and as long as Transliteration is off in Gadgetbridge's Bangle.js settings (the default) then your messages should then be able to render.
  • Can I rearrange the widgets? Yes! You can usually remove a widget just by uninstalling the relevant app from the app loader, and to move them around you can use the widget editor app: https://banglejs.com/apps/?id=wid_edit
  • When my Bangle.js is set as a HID device, my phone's onscreen keyboard doesn't display In your phone's Bluetooth settings, click on the settings icon for the Bangle's connection, then Keyboard Settings, then make sure that the option for "use on-screen keyboard" is checked on

Developing Apps for Bangle JS

  • Bangle JS Tutorials
  • How can I learn Javascript? The Tutorials at W3Schools is a good place to start from scratch. But also try out other developers app code and make a few modifications. Looking at apps that are close to what you want to do and modifying the code is a good way to develop quickly.
  • Espruino API Reference
  • The Bangle github README provides lots of information with regards to packaging your app into your app loader.
  • How can I best document my App ? Please ensure you create a README file. Screenshots are really helpful, and enable users to quickly decide if they want to use your app.
  • How can I get a screenshot Run your app, connect using the IDE, in the left hand side type g.dump(); click on the image and download it. For Bangle JS 1, you will need to take a photo of the watch or run the app in the emulator and use the screenshot facility in the emulator.
  • What size should app icons be? 48x48 pixels.
  • My App wont load from my AppLoader Check that your apps.json file is correct. Check that your code subdirectory name matches the id for the App.
  • All apps come up as unknown in my AppLoader check you have not missed a comma or bracket in your apps.json file.
  • How long does it take for my App to appear in the official loader? see this conversation

Glossary

  • App Loader / App Store means this website which can be used to load apps onto the Bangle
  • Web IDE means this website which can be used to write/debug applications for Bangle.js
  • Emulator is fake Bangle.js that runs inside the Web Browser and can be used to test some features on the Bangle without a real device. It can be accessed from the connection menu of the Web IDE
  • The Launcher is the menu that lets you choose which app to 'launch'. It's usually accessible from the Clock by short-pressing the button.
  • Locked is when the touchscreen is made inactive, so that touches on the watch face will not have any effect.
  • Unlocked is when the touchscreen is active and usable (a button press usually unlocks the screen, but unlock methods can be configured in the settings app)

Firmware Updates

Two types of software run on Bangle.js:

  • There's the apps, which are JavaScript and can be updated with the App Loader
  • Then there's the Bangle.js firmware, which is the watch's OS. There is a firmware updater in the App Loader which we'd recommend you use on Bangle.js 2. For Bangle.js 1 or more information, check out the Bangle.js 1 or Bangle.js 2 instructions to update it.

Recommended Apps

Once you're up and running and connected with the App Loader you might want to install some apps. Here are some recommended ones:

Languages provides translations for different countries. At the moment this will not translate apps, but will change dates, speed, distance, temperature, etc. More info here.

If you have too many applications in the launcher, you may want to look at Folder launcher. Organizing applications into folders allows access without excessive scrolling, organization can be done on watch or from web browser.

Timekeeping

Crystal in Bangle.js2 is not calibrated, so its timekeeping is 'not great' unless you stay connected to a companion device like an Android/iOS phone. For usage without cellphone, you may want to install Adjust clock.

Bangle.js2 does not have a speaker, but vibration motor can be used for alarms. Use Alarms & Timers tool for that.

Battery can last for weeks with light use, but it is easy to drain battery within hours with heavy GPS use. Use Drained to prevent that.

Phone integration

Android app provides integration with the Gadgetbridge app on your Android phone and allows you to see messages and other information on your watch. iOS app provides similar functionality for Apple devices.

Hardware sensors

Pedometer Widget will show your current step count for the day in the top bar. Heart Rate Monitor will display PPG (heart rate) measurements from the heart rate sensor on Bangle.js.

Altimeter in Bangle.js2 is very fast and accurate, but needs calibration. You can use Altimeter to calibrate it if you know either pressure or current altitude. Rest of the system will then use that calibration, until reboot. You may need to do calibration daily.

GPS functionality

The GPS in Bangle.js2 is not as good as those in modern cellphones. Loading up to date (within 48 hours) AGPS data into watch helps a lot. You can do this manually with the AGPS Updater app or you can use A-GPS Data Downloader App. Alternatively, remember to turn on GPS in a place with great view of sky to download almanac from the satellites. Note that cold start (eg no AGPS data) can take few minutes. You can use Sky Spy to monitor signal acquisition. Note that trying to acquire GPS indoor will usually not be possible, and that doing cold start under trees may take hour or not work at all. But if you acquire fix in open area, GPS will usually continue working under the trees.

For recording tracks use Recorder. It can also record heart rate/steps/etc and then export them as GPX/KML/CSV files for use in apps like Strava. It is available as a library for other apps, so you can use Run+ to display statistics such as speed and distance covered as a bonus when you keep it in foreground and have good GPS reception.

Navigation to GPS coordinates is supported. Use Waypoints to edit waypoints from web browser or from watch. You can also mark current position on the watch. Waypointer Moto can then be used to display arrow and distance to given waypoint.

Bangle.js2 is not a great platform for displaying maps, but still some solutions exist. Open Street Map can be used for displaying raster maps, it can also display past track and waypoints.

Updates

Feel free to edit this wiki and add new suggested apps and information!

Add a custom sidebar
Clone this wiki locally