Bram
/
BangleApps
forked from FOSS/BangleApps
1
0
Fork 0
Code Pull Requests Activity

Updated docs!

master
Gordon Williams 2022-01-19 16:21:07 +00:00
parent 7feaed5b8e
commit 2a813e221a
2 changed files with 32 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@ -12,7 +12,7 @@ and that it is not licensed in another way that would make this impossible.
## How does it work? ## How does it work?
* A list of apps is in `apps.json` * A list of apps is in `apps.json` (this is auto-generated from all the `apps/yourapp/metadata.json` using Jekyll or `bin/create_apps_json.sh`)
* Each element references an app in `apps/<id>` which is uploaded * Each element references an app in `apps/<id>` which is uploaded
* When it starts, BangleAppLoader checks the JSON and compares * When it starts, BangleAppLoader checks the JSON and compares
it with the files it sees in the watch's storage. it with the files it sees in the watch's storage.
@ -53,10 +53,10 @@ easily distinguish between file types, we use the following:
is limited to 28 char filenames and appends a file extension (eg `.js`) so please is limited to 28 char filenames and appends a file extension (eg `.js`) so please
try and keep filenames short to avoid overflowing the buffer. try and keep filenames short to avoid overflowing the buffer.
* Create a folder called `apps/<id>`, lets assume `apps/myappid` * Create a folder called `apps/<id>`, lets assume `apps/myappid`
* We'd recommend that you copy files from 'Example Applications' (below) as a base, or... * We'd recommend that you copy files from one of the Examples in `apps/_example_*` (see below), or...
* `apps/myappid/app.png` should be a 48px icon * `apps/myappid/app.png` should be a 48px icon
* Use http://www.espruino.com/Image+Converter to create `apps/myappid/app-icon.js`, using a 1 bit, 4 bit or 8 bit Web Palette "Image String" * Use http://www.espruino.com/Image+Converter to create `apps/myappid/app-icon.js`, using a 1 bit, 4 bit or 8 bit Web Palette "Image String"
* Create an entry in `apps.json` as follows: * Create/modify `apps/myappid/metadata.json` as follows:
``` ```
{ "id": "myappid", { "id": "myappid",
@ -116,8 +116,7 @@ and set it to `Load default application`.
To make the process easier we've come up with some example applications that you can use as a base To make the process easier we've come up with some example applications that you can use as a base
when creating your own. Just come up with a unique name (ideally lowercase, under 20 chars), copy `apps/_example_app` when creating your own. Just come up with a unique name (ideally lowercase, under 20 chars), copy `apps/_example_app`
or `apps/_example_widget` to `apps/myappid`, and add `apps/_example_X/add_to_apps.json` to or `apps/_example_widget` to `apps/myappid`, and edit `apps/myappid/metadata.json` accordingly.
`apps.json`.
**Note:** the max filename length is 28 chars, so we suggest an app ID of under **Note:** the max filename length is 28 chars, so we suggest an app ID of under
20 so that when `.app.js`/etc gets added to the end the filename isn't cropped. 20 so that when `.app.js`/etc gets added to the end the filename isn't cropped.
@ -131,7 +130,7 @@ The app example is available in [`apps/_example_app`](apps/_example_app)
Apps are listed in the Bangle.js menu, accessible from a clock app via the middle button. Apps are listed in the Bangle.js menu, accessible from a clock app via the middle button.
* `add_to_apps.json` - insert into `apps.json`, describes the app to bootloader and loader * `metadata.json` - describes the app to bootloader and loader
* `app.png` - app icon - 48x48px * `app.png` - app icon - 48x48px
* `app-icon.js` - JS version of the icon (made with http://www.espruino.com/Image+Converter) for use in Bangle.js's menu * `app-icon.js` - JS version of the icon (made with http://www.espruino.com/Image+Converter) for use in Bangle.js's menu
* `app.js` - app code * `app.js` - app code
@ -144,11 +143,11 @@ Use the Espruino [image converter](https://www.espruino.com/Image+Converter) and
Follow this steps to create a readable icon as image string. Follow this steps to create a readable icon as image string.
1. upload a png file 1. upload a 48x48 png file - THE IMAGE SHOULD BE 48x48 OR LESS
2. set _X_ Use Compression 2. set _X_ Use Compression
3. set _X_ Transparency (optional) 3. set _X_ Transparency (optional)
4. set Diffusion: _flat_ 4. set Diffusion: _flat_
5. set Colours: _1 bit_, _4 bit_ or _8 bit Web Palette_ 5. set Colours: _1 bit_, any of the Optimised options, or _8 bit Web Palette_ are best
6. set Output as: _Image String_ 6. set Output as: _Image String_
Replace this line with the image converter output: Replace this line with the image converter output:
@ -157,6 +156,8 @@ Replace this line with the image converter output:
require("heatshrink").decompress(atob("mEwwJC/AH4A/AH4AgA==")) require("heatshrink").decompress(atob("mEwwJC/AH4A/AH4AgA=="))
``` ```
**Do not add a trailing semicolon**
You can also use this converter for creating images you like to draw with `g.drawImage()` with your app. You can also use this converter for creating images you like to draw with `g.drawImage()` with your app.
Apps that need widgets can call `Bangle.loadWidgets()` **once** at startup to load Apps that need widgets can call `Bangle.loadWidgets()` **once** at startup to load
@ -167,7 +168,7 @@ has call to completely clear the screen. Widgets themselves will update as and w
The widget example is available in [`apps/_example_widget`](apps/_example_widget) The widget example is available in [`apps/_example_widget`](apps/_example_widget)
* `add_to_apps.json` - insert into `apps.json`, describes the widget to bootloader and loader * `metadata.json` - describes the widget to bootloader and loader
* `widget.js` - widget code * `widget.js` - widget code
Widgets are just small bits of code that run whenever an app that supports them Widgets are just small bits of code that run whenever an app that supports them
@ -203,7 +204,7 @@ and which gives information about the app for the Launcher.
// if it's 'clock' then it'll be loaded by default at boot time // if it's 'clock' then it'll be loaded by default at boot time
// if this is 'bootloader' then it's code that is run at boot time, but is not in a menu // if this is 'bootloader' then it's code that is run at boot time, but is not in a menu
"version":"1.23", "version":"1.23",
// added by BangleApps loader on upload based on apps.json // added by BangleApps loader on upload based on metadata.json
"files:"file1,file2,file3", "files:"file1,file2,file3",
// added by BangleApps loader on upload - lists all files // added by BangleApps loader on upload - lists all files
// that belong to the app so it can be deleted // that belong to the app so it can be deleted
@ -215,7 +216,7 @@ and which gives information about the app for the Launcher.
} }
``` ```
### `apps.json` format ### `metadata.json` format
``` ```
{ "id": "appid", // 7 character app id { "id": "appid", // 7 character app id
@ -294,9 +295,9 @@ and which gives information about the app for the Launcher.
* storage is used to identify the app files and how to handle them * storage is used to identify the app files and how to handle them
* data is used to clean up files when the app is uninstalled * data is used to clean up files when the app is uninstalled
### `apps.json`: `custom` element ### `metadata.json`: `custom` element
Apps that can be customised need to define a `custom` element in `apps.json`, Apps that can be customised need to define a `custom` element in `metadata.json`,
which names an HTML file in that app's folder. which names an HTML file in that app's folder.
When `custom` is defined, the 'upload' button is replaced by a customize When `custom` is defined, the 'upload' button is replaced by a customize
@ -304,7 +305,7 @@ button, and when clicked it opens the HTML page specified in an iframe.
In that HTML file you're then responsible for handling a button In that HTML file you're then responsible for handling a button
press and calling `sendCustomizedApp` with your own customised press and calling `sendCustomizedApp` with your own customised
version of what's in `apps.json`: version of what's in `metadata.json`:
``` ```
<html> <html>
@ -336,9 +337,9 @@ for a clean example.
and will never be loaded. This is so the app loader can tell if it's a JavaScript and will never be loaded. This is so the app loader can tell if it's a JavaScript
file based on the extension, and if so it can minify and pretokenise it. file based on the extension, and if so it can minify and pretokenise it.
### `apps.json`: `interface` element ### `metadata.json`: `interface` element
Apps that create data that can be read back can define a `interface` element in `apps.json`, Apps that create data that can be read back can define a `interface` element in `metadata.json`,
which names an HTML file in that app's folder. which names an HTML file in that app's folder.
When `interface` is defined, a `Download from App` button is added to When `interface` is defined, a `Download from App` button is added to
@ -402,7 +403,7 @@ Example `settings.js`
E.showMenu(appMenu) E.showMenu(appMenu)
}) })
``` ```
In this example the app needs to add `myappid.settings.js` to `storage` in `apps.json`. In this example the app needs to add `myappid.settings.js` to `storage` in `metadata.json`.
It should also add `myappid.json` to `data`, to make sure it is cleaned up when the app is uninstalled. It should also add `myappid.json` to `data`, to make sure it is cleaned up when the app is uninstalled.
```json ```json
{ "id": "myappid", { "id": "myappid",

14
bin/create_apps_json.sh
View File

@ -1,4 +1,18 @@
#!/bin/bash #!/bin/bash
# ================================================================
# apps.json used to contain the metadata for every app. Now the
# metadata is stored in each apps's directory - app/yourapp/metadata.js
#
# The app loader still wants all the data in one file, so normally
# with GitHub pages, Jekyll is automatically run and creates a working
# apps.json
#
# However if you're hosting locally, or not on GitHub pages then you
# will want to create apps.json yourself. You can do that by installing
# and running Jekyll, OR the easier option is just to run this script.
#
# If you do this, please do not attempt to commit your modified
# apps.json back into the main BangleApps repository!
cd `dirname $0`/.. cd `dirname $0`/..
echo "[" > apps.json echo "[" > apps.json