kamoji-dev 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,8 +2,9 @@
2
2
 
3
3
  Develop [Kamoji Mini Apps](https://docs.kamoji.bot/docs/apps) on your own Kamoji: edit the files in
4
4
  your editor, save, and the mini app is checked, installed over Bluetooth and reopened on Kamoji's
5
- screen within seconds. With a USB cable plugged in, Kamoji's log (your `print()` lines, Lua errors,
6
- CPU budget warnings, crashes) streams into the same terminal.
5
+ screen within seconds; a save sends only the files that changed (firmware 0.3.3). Your app's log
6
+ (`print()` lines, Lua errors, CPU budget warnings) streams into the same terminal: over the USB
7
+ cable when one is plugged in (crashes too), else over Bluetooth (firmware 0.3.3).
7
8
 
8
9
  ```sh
9
10
  npm i -g kamoji-dev
@@ -13,7 +14,8 @@ kamoji dev ./my-app
13
14
  or without installing: `npx kamoji-dev dev ./my-app`.
14
15
 
15
16
  Needs Node.js 20 or newer, a computer with Bluetooth LE (macOS, Windows 10+, Linux) and a Kamoji
16
- with firmware 0.3.0 or newer (mini apps from 0.1.80).
17
+ with firmware 0.3.0 or newer (mini apps from 0.1.80; 0.3.3 for changed-files reloads and the log
18
+ over Bluetooth).
17
19
 
18
20
  ## Before you start
19
21
 
@@ -34,17 +36,18 @@ with firmware 0.3.0 or newer (mini apps from 0.1.80).
34
36
 
35
37
  | Command | What it does |
36
38
  |---|---|
37
- | `kamoji dev <folder>` | Check, install and open the mini app; then again on every save (400 ms after the last change). Keys while it runs: Enter = install again, `o` = open, `s` = screenshot, `b` = restart Kamoji, `q` = quit |
39
+ | `kamoji dev <folder>` | Check, install and open the mini app; then again on every save (400 ms after the last change), sending only the changed files. Keys while it runs: Enter = install again (every file), `o` = open, `s` = screenshot, `b` = restart Kamoji, `q` = quit |
38
40
  | `kamoji install <folder>` | Check, install and open once (exit code 0 = on screen) |
39
41
  | `kamoji check <folder>` | Only check the folder, like the Mini Apps store does (`--json` for tools) |
40
42
  | `kamoji apps` | List the mini apps on Kamoji, with their mode numbers and sizes |
41
43
  | `kamoji shot` | Save a screenshot (over USB when plugged in, else Bluetooth) to `./kamoji-shots` |
42
- | `kamoji logs` | Kamoji's USB log (`--app <id>` to follow one app, `--verbose` for every line) |
44
+ | `kamoji logs` | Kamoji's log: USB, or over Bluetooth without a cable or with `--ble` (`--app <id>` to follow one app, `--verbose` for every USB line) |
43
45
  | `kamoji forget` | Kamoji forgets this computer, and the key is deleted |
44
46
 
45
47
  Options: `--device KMJ-XXXX` (several Kamoji nearby; the last four characters are enough),
46
48
  `--port /dev/cu.usbmodemXXXX` (USB port, found by itself otherwise), `--ble` (no USB log even with a
47
- cable), `--usb` (require the cable), `--out DIR` (screenshots), `--reboot` (restart Kamoji by itself
49
+ cable: the app log comes over Bluetooth), `--ble-logs` (the app log over Bluetooth even with a cable;
50
+ USB then adds only crashes and resets), `--usb` (require the cable), `--out DIR` (screenshots), `--reboot` (restart Kamoji by itself
48
51
  when the mini app's Bluetooth services need it), `--no-lua`, `--verbose`.
49
52
 
50
53
  What you see:
@@ -59,8 +62,21 @@ What you see:
59
62
  10:02:16 [entered] [my-app] entered in 118 ms: 4 bindings, Lua 2311 bytes
60
63
  10:02:17 [print] tick 1
61
64
  10:02:19 [warn] [my-app] main.lua: main.lua:12: attempt to perform arithmetic on a nil value
65
+ 10:02:31 Updated my-app: 1 file changed (main.lua, 0.4 KB) in 0.6 s.
66
+ 10:02:31 my-app is on screen (mode 7, 0.8 s after the first byte).
62
67
  ```
63
68
 
69
+ ### Firmware 0.3.3 and older
70
+
71
+ | | Firmware 0.3.3 or newer | Older firmware |
72
+ |---|---|---|
73
+ | A save | Only the changed and new files are sent, removed ones deleted (`APP_FILES`, `APP_EDIT`, `APP_DELETE`). The app's `config.json` and `data/` are never deleted. Same files already there: `Nothing changed` | Every file (a note says so once) |
74
+ | Log without a USB cable | Over Bluetooth (`APP_LOG`): `print()`, lifecycle, warnings, Lua errors, at most 20 lines a second (`Kamoji dropped N log line(s)` otherwise). Crashes and resets need the cable | None (a note says so once) |
75
+ | Finding Kamoji | Fast for 30 s after a boot or a disconnect | Up to 30 s on Wi-Fi |
76
+
77
+ Whenever Kamoji can't do a changed-files update (the app isn't on it yet, it answers an error, a
78
+ line of the file list got lost), the tool sends every file instead; Enter always does.
79
+
64
80
  ## What it checks before sending
65
81
 
66
82
  The store's rules (manifest `id`, `version`, `api_version` 1, known `permissions` / `features` /
@@ -77,9 +93,11 @@ are never sent. The full table is in `spec/VALIDATION.md` of the source.
77
93
  The same Bluetooth commands as the Kamoji app's **Install from file**
78
94
  ([Sideloading](https://docs.kamoji.bot/docs/apps/sideloading#bluetooth-install-protocol)):
79
95
  `APP_PUT` + `ASSET_DATA` per file, `APP_COMMIT`, then `SET_MODE` to the app's mode (from
80
- `APPS_LIST`). An install replaces the whole mini app, so every save sends every file (unchanged
81
- saves are skipped); the app's settings (`config.json`) and `data/` stay. A mini app that is on
82
- screen restarts with the new version. Bluetooth is slow-ish: about 3-15 KB/s depending on the
96
+ `APPS_LIST`). From firmware 0.3.3 a save of an installed app starts with `APP_FILES` (the md5 and
97
+ size of every installed file) and `APP_EDIT` (Kamoji stages a copy of it), then sends only what
98
+ changed and commits the same way; older firmware gets every file (unchanged saves are skipped). The
99
+ app's settings (`config.json`) and `data/` stay. A mini app that is on screen restarts with the new
100
+ version. Bluetooth is slow-ish: about 3-15 KB/s depending on the
83
101
  computer, so a 10 KB app reloads in 1-3 s.
84
102
 
85
103
  Over USB the tool only reads: Kamoji has no install over USB (that would mean rewriting its whole
@@ -102,13 +120,14 @@ The Python tool in the Kamoji repositories (`kamoji_dev.py`) uses the same files
102
120
  | needs firmware … or newer | Update Kamoji in the Kamoji app |
103
121
  | Kamoji is out of storage space | Remove a mini app in the Kamoji app (Apps) |
104
122
  | its Bluetooth services go live after a restart | Press `b` (or run with `--reboot`) |
105
- | No USB cable: no Kamoji log | Plug in a USB-C **data** cable; `--port` if several boards are plugged in |
123
+ | This firmware sends no app log over Bluetooth | Update Kamoji to 0.3.3, or plug in a USB-C **data** cable; `--port` if several boards are plugged in |
124
+ | This firmware installs whole mini apps only | Nothing to do (every file is sent); update Kamoji to 0.3.3 for faster reloads |
106
125
 
107
126
  ## Development
108
127
 
109
128
  ```sh
110
129
  npm test # node:test, fake Kamoji, no device needed
111
- node spec/make-conversation.mjs # after changing the protocol: re-record spec/conversation.json
130
+ node spec/make-conversation.mjs # after changing the protocol: re-record spec/conversation*.json
112
131
  ```
113
132
 
114
133
  Bluetooth is [@stoprocent/noble](https://github.com/stoprocent/noble) (maintained, prebuilt for
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kamoji-dev",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Develop Kamoji Mini Apps on your own Kamoji: check, install over Bluetooth and reload on every save, with the USB log and screenshots.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -18,7 +18,12 @@
18
18
  "scripts": {
19
19
  "test": "node --test test/*.test.js"
20
20
  },
21
- "keywords": ["kamoji", "mini-apps", "ble", "esp32"],
21
+ "keywords": [
22
+ "kamoji",
23
+ "mini-apps",
24
+ "ble",
25
+ "esp32"
26
+ ],
22
27
  "homepage": "https://docs.kamoji.bot/docs/apps",
23
28
  "license": "MIT",
24
29
  "dependencies": {
package/src/check.js CHANGED
@@ -1,54 +1,13 @@
1
1
  // Reading a mini app folder and checking it before it is sent: the rules and their ids are in
2
- // spec/VALIDATION.md (shared with the Python worker/rig/kamoji_dev.py of kamoji-cms).
3
- //
4
- // Copied from kamoji-cms src/utils/appBundle.ts (APP_ID_RE, SEMVER_RE, APP_PERMISSIONS, APP_FEATURES,
5
- // APP_PLATFORMS, BUNDLE_LIMITS, checkAppPath) because this package is published on its own: keep both
6
- // in step when the store's rules change.
2
+ // spec/VALIDATION.md (shared with the Python worker/rig/kamoji_dev.py of kamoji-cms). The rules themselves
3
+ // are in core/check.js (shared with the web IDE); this file reads the folder and runs the Lua compiler.
7
4
  import fs from 'node:fs'
8
5
  import path from 'node:path'
9
6
  import { spawnSync } from 'node:child_process'
7
+ import { checkFiles, isJunk } from './core/check.js'
10
8
  import { md5Hex } from './protocol.js'
11
9
 
12
- export const APP_ID_RE = /^[a-z0-9][a-z0-9-]{1,39}$/
13
- export const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
14
- export const VERSION_RE = /^v?\d+(\.\d+){1,3}(-[0-9A-Za-z.-]+)?$/
15
- export const APP_PERMISSIONS = [
16
- 'sensors.imu', 'sensors.light', 'sensors.mic', 'sensors.env', 'sensors.obd', 'events.drive', 'events.device',
17
- 'touch', 'net.http', 'net.mqtt', 'net.phone', 'phone.navigation', 'ble.gatt',
18
- ]
19
- export const APP_FEATURES = ['gyro', 'temperature', 'light', 'microphone', 'fft', 'wifi', 'ble', 'gatt', 'mqtt', 'http', 'time', 'rgb_leds']
20
- export const APP_PLATFORMS = ['android', 'ios']
21
- export const PARAM_TYPES = ['number', 'bool', 'string', 'enum', 'color', 'secret']
22
- export const WIDGET_TYPES = ['label', 'rect', 'circle', 'arc', 'bar', 'line', 'polyline', 'bitmap', 'chart', 'image']
23
- export const ALIGNS = ['center', 'top_left', 'top_mid', 'top_right', 'left_mid', 'right_mid', 'bottom_left', 'bottom_mid', 'bottom_right']
24
- export const LIMITS = { maxTotalBytes: 2 * 1024 * 1024, maxFiles: 64, maxPathBytes: 63, maxDepth: 3, maxManifestBytes: 16384 }
25
-
26
- const SKIP_NAMES = new Set(['.DS_Store', 'Thumbs.db', '__MACOSX', 'node_modules', '4913'])
27
-
28
- /** Files an editor or the OS leaves next to the real ones: never sent. */
29
- export function isJunk(name) {
30
- return (
31
- name.startsWith('.') || SKIP_NAMES.has(name) || name.endsWith('~') || /\.(swp|swo|swx|tmp)$/i.test(name) ||
32
- /^#.*#$/.test(name)
33
- )
34
- }
35
-
36
- /** Same as the store's checkAppPath: an error message, or null. */
37
- export function checkAppPath(p) {
38
- if (!p) return 'empty path'
39
- if (p.startsWith('/') || /^[a-zA-Z]:/.test(p)) return `absolute path not allowed: ${p}`
40
- if (p.includes('\\')) return `backslash in path: ${p}`
41
- if (/[\x00-\x1f\x7f]/.test(p)) return `control character in path: ${JSON.stringify(p)}`
42
- const segments = p.split('/')
43
- for (const s of segments) {
44
- if (s === '') return `empty path segment: ${p}`
45
- if (s === '..' || s === '.') return `relative segment not allowed: ${p}`
46
- if (s.startsWith('.')) return `names starting with "." are not allowed: ${p}`
47
- }
48
- if (Buffer.byteLength(p, 'utf8') > LIMITS.maxPathBytes) return `path longer than ${LIMITS.maxPathBytes} bytes: ${p}`
49
- if (segments.length > LIMITS.maxDepth) return `path deeper than ${LIMITS.maxDepth} levels: ${p}`
50
- return null
51
- }
10
+ export * from './core/check.js'
52
11
 
53
12
  /**
54
13
  * Every file of the folder that would be sent: [{path, data, md5}] sorted by path, plus what was skipped.
@@ -77,20 +36,6 @@ export function readAppFolder(folder) {
77
36
  return { files, skipped }
78
37
  }
79
38
 
80
- /** Version compare like the firmware checks: 0.3.10 > 0.3.9, a release after its -rc. */
81
- export function compareVersions(a, b) {
82
- const parse = (v) => {
83
- const m = /^v?(\d+(?:\.\d+)*)(?:-(.*))?$/.exec(String(v ?? '').trim())
84
- if (!m) return [[0, 0, 0, 0], '']
85
- const nums = [...m[1].split('.').map(Number), 0, 0, 0, 0].slice(0, 4)
86
- return [nums, m[2] ?? '~']
87
- }
88
- const [na, pa] = parse(a)
89
- const [nb, pb] = parse(b)
90
- for (let i = 0; i < 4; i++) if (na[i] !== nb[i]) return na[i] < nb[i] ? -1 : 1
91
- return pa === pb ? 0 : pa < pb ? -1 : 1
92
- }
93
-
94
39
  let luacCache
95
40
  /** The Lua compiler on this computer: { cmd, version: '5.4' | '5.5' | … } or null. */
96
41
  export function findLuac() {
@@ -118,159 +63,15 @@ function checkLua(file, add) {
118
63
  return true
119
64
  }
120
65
 
121
- function checkLayout(file, add) {
122
- let layout
123
- try {
124
- layout = JSON.parse(file.data.toString('utf8').replace(/^/, ''))
125
- } catch (e) {
126
- add('error', 'layout-json', `not valid JSON: ${e.message}`, file.path)
127
- return
128
- }
129
- let widgets
130
- if (Array.isArray(layout)) widgets = layout
131
- else if (layout && typeof layout === 'object' && Array.isArray(layout.widgets)) widgets = layout.widgets
132
- else {
133
- add('error', 'layout-shape', 'must be an array of widgets, or an object with a "widgets" array', file.path)
134
- return
135
- }
136
- widgets.forEach((w, i) => {
137
- const where = `${file.path} widget ${i + 1}`
138
- if (!w || typeof w !== 'object' || Array.isArray(w)) {
139
- add('warning', 'widget-type', 'not an object (skipped by Kamoji)', where)
140
- return
141
- }
142
- if (!WIDGET_TYPES.includes(w.type))
143
- add('warning', 'widget-type', `type ${JSON.stringify(w.type)} is not a widget Kamoji draws (${WIDGET_TYPES.join(', ')})`, where)
144
- if (w.align !== undefined && !ALIGNS.includes(w.align)) add('warning', 'align', `align ${JSON.stringify(w.align)} is not one of ${ALIGNS.join(', ')}`, where)
145
- for (const [k, v] of Object.entries(w)) {
146
- if (typeof v === 'string' && v.split('{{').length - 1 > v.split('}}').length - 1)
147
- add('warning', 'binding-braces', `"${k}" opens {{ without closing }}`, where)
148
- }
149
- })
150
- if (!Array.isArray(layout) && layout.on !== undefined) {
151
- if (!layout.on || typeof layout.on !== 'object' || Array.isArray(layout.on)) add('error', 'layout-on', '"on" must be an object', file.path)
152
- else
153
- for (const [k, v] of Object.entries(layout.on))
154
- if (typeof v !== 'string') add('error', 'layout-on', `"on.${k}" must be a string of Lua statements`, file.path)
155
- }
156
- }
157
-
158
- function checkManifest(m, folderName, add) {
159
- const where = 'manifest.json'
160
- if (typeof m.id !== 'string' || !APP_ID_RE.test(m.id))
161
- add('error', 'id', '"id": lowercase letters, digits and "-", starting with a letter or digit, 2 to 40 characters', where)
162
- else if (folderName && m.id !== folderName)
163
- add('warning', 'id-folder', `"id" is "${m.id}" but the folder is "${folderName}" (the store and Kamoji use the id as the folder name)`, where)
164
- if (typeof m.version !== 'string' || !SEMVER_RE.test(m.version))
165
- add('error', 'version', '"version" must be a version like 1.0.0 (the store needs it)', where)
166
- if (m.api_version !== 1) add('error', 'api-version', '"api_version" must be 1', where)
167
- const perms = m.permissions
168
- if (perms !== undefined) {
169
- if (!Array.isArray(perms)) add('error', 'permissions', '"permissions" must be an array', where)
170
- else {
171
- const unknown = perms.filter((p) => !APP_PERMISSIONS.includes(p))
172
- if (unknown.length) add('error', 'permissions', `unknown permissions: ${unknown.join(', ')} (known: ${APP_PERMISSIONS.join(', ')})`, where)
173
- }
174
- }
175
- if (m.features !== undefined) {
176
- if (!Array.isArray(m.features)) add('error', 'features', '"features" must be an array', where)
177
- else {
178
- const unknown = m.features.filter((f) => !APP_FEATURES.includes(f))
179
- if (unknown.length) add('error', 'features', `unknown features: ${unknown.join(', ')} (known: ${APP_FEATURES.join(', ')})`, where)
180
- }
181
- }
182
- if (m.platforms !== undefined) {
183
- if (!Array.isArray(m.platforms) || m.platforms.length === 0) add('error', 'platforms', '"platforms" must be a non-empty array', where)
184
- else {
185
- const unknown = m.platforms.filter((p) => !APP_PLATFORMS.includes(p))
186
- if (unknown.length) add('error', 'platforms', `unknown platforms: ${unknown.join(', ')}`, where)
187
- }
188
- }
189
- if (m.min_firmware !== undefined && (typeof m.min_firmware !== 'string' || !VERSION_RE.test(m.min_firmware)))
190
- add('error', 'min-firmware', '"min_firmware" must be a version string like "0.3.0"', where)
191
- const has = (p) => Array.isArray(perms) && perms.includes(p)
192
- if (m.ble !== undefined && !has('ble.gatt')) add('error', 'ble-permission', '"ble" needs the "ble.gatt" permission (Kamoji refuses the install)', where)
193
- if (m.http !== undefined && !has('net.http')) add('warning', 'http-permission', '"http" without the "net.http" permission: http is nil in Lua', where)
194
- if ((m.ble !== undefined || m.http !== undefined) &&
195
- (typeof m.min_firmware !== 'string' || compareVersions(m.min_firmware, '0.3.0') < 0))
196
- add('warning', 'min-firmware-030', '"ble" and "http" need firmware 0.3.0: set "min_firmware": "0.3.0"', where)
197
- if (m.params !== undefined) {
198
- if (!Array.isArray(m.params)) add('error', 'params', '"params" must be an array', where)
199
- else {
200
- const seen = new Set()
201
- m.params.forEach((p, i) => {
202
- const at = `params[${i}]`
203
- if (!p || typeof p !== 'object' || Array.isArray(p)) return add('error', 'params', `${at} must be an object`, where)
204
- if (typeof p.key !== 'string' || !p.key) add('error', 'params', `${at} needs a "key"`, where)
205
- else if (seen.has(p.key)) add('error', 'params', `${at}: key "${p.key}" is used twice`, where)
206
- else seen.add(p.key)
207
- const type = p.type ?? 'string'
208
- if (!PARAM_TYPES.includes(type)) add('error', 'params', `${at}: type ${JSON.stringify(type)} is not one of ${PARAM_TYPES.join(', ')}`, where)
209
- if (type === 'enum' && (!Array.isArray(p.options) || p.options.length === 0))
210
- add('error', 'params', `${at}: an enum needs "options"`, where)
211
- })
212
- }
213
- }
214
- }
215
-
216
66
  /**
217
67
  * Check a folder. Returns { problems:[{level,id,message,where}], errors, warnings, manifest, appId, files, skipped, bytes }.
218
68
  * @param {{lua?: boolean}} [opts] lua: false skips the Lua compiler
219
69
  */
220
70
  export function checkApp(folder, opts = {}) {
221
- const problems = []
222
- const add = (level, id, message, where) => problems.push({ level, id, message, where })
223
71
  const folderName = path.basename(path.resolve(folder))
224
72
  const { files, skipped } = readAppFolder(folder)
225
- if (skipped.length) add('info', 'skipped', `not sent: ${skipped.join(', ')}`)
226
- for (const f of files) {
227
- const err = checkAppPath(f.path)
228
- if (err) add('error', 'path', err, f.path)
229
- }
230
- if (files.length > LIMITS.maxFiles) add('error', 'too-many-files', `${files.length} files (at most ${LIMITS.maxFiles})`)
231
- const bytes = files.reduce((n, f) => n + f.data.length, 0)
232
- if (bytes > LIMITS.maxTotalBytes) add('error', 'too-large', `${Math.ceil(bytes / 1024)} KB (at most 2 MB)`)
233
-
234
- let manifest = null
235
- const mf = files.find((f) => f.path === 'manifest.json')
236
- if (!mf) add('error', 'manifest-missing', 'no manifest.json at the root of the folder')
237
- else if (mf.data.length > LIMITS.maxManifestBytes) add('error', 'manifest-size', `manifest.json is ${mf.data.length} bytes (at most 16 KB)`, 'manifest.json')
238
- else {
239
- try {
240
- manifest = JSON.parse(mf.data.toString('utf8').replace(/^/, ''))
241
- if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
242
- manifest = null
243
- add('error', 'manifest-json', 'manifest.json must be a JSON object', 'manifest.json')
244
- }
245
- } catch (e) {
246
- add('error', 'manifest-json', `not valid JSON: ${e.message}`, 'manifest.json')
247
- }
248
- if (manifest) checkManifest(manifest, folderName, add)
249
- }
250
- const layout = files.find((f) => f.path === 'layout.json')
251
- if (layout) checkLayout(layout, add)
252
- if (opts.lua !== false) {
253
- const luaFiles = files.filter((f) => f.path.endsWith('.lua'))
254
- if (luaFiles.length) {
255
- let ran = false
256
- for (const f of luaFiles) ran = checkLua(f, add) || ran
257
- if (!ran) add('info', 'lua-missing', 'no Lua compiler (luac5.4 / luac) found: Lua is checked by Kamoji only')
258
- }
259
- }
260
- const appId = manifest && typeof manifest.id === 'string' && APP_ID_RE.test(manifest.id) ? manifest.id : null
261
- return {
262
- problems,
263
- errors: problems.filter((p) => p.level === 'error'),
264
- warnings: problems.filter((p) => p.level === 'warning'),
265
- manifest,
266
- appId,
267
- files,
268
- skipped,
269
- bytes,
270
- }
271
- }
272
-
273
- /** The md5 of the whole set (paths + contents): unchanged files are not sent again. */
274
- export function bundleHash(files) {
275
- return md5Hex(Buffer.from(files.map((f) => `${f.path}\0${f.md5}`).join('\n')))
73
+ return checkFiles(
74
+ { files, skipped, folderName },
75
+ opts.lua === false ? {} : { luaCheck: checkLua, luaMissing: 'no Lua compiler (luac5.4 / luac) found: Lua is checked by Kamoji only' },
76
+ )
276
77
  }
package/src/cli.js CHANGED
@@ -20,22 +20,24 @@ Usage:
20
20
  kamoji check <folder> only check the folder (manifest, layout, Lua) like the Mini Apps store
21
21
  kamoji apps list the mini apps on Kamoji
22
22
  kamoji shot save a screenshot of Kamoji's screen
23
- kamoji logs show Kamoji's USB log (USB cable needed)
23
+ kamoji logs show Kamoji's log (USB; over Bluetooth without a cable, or with --ble)
24
24
  kamoji forget make Kamoji forget this computer, and delete its key
25
25
 
26
26
  Options:
27
27
  --device KMJ-XXXX which Kamoji (needed when several are near)
28
28
  --port PATH USB serial port for the log (default: found by itself)
29
- --ble Bluetooth only: no USB log even with a cable
29
+ --ble Bluetooth only: no USB log even with a cable (the app log comes over Bluetooth)
30
+ --ble-logs the app log over Bluetooth even with a USB cable (USB then adds crashes and resets)
30
31
  --usb require the USB cable (log and screenshots over USB)
31
32
  --out DIR where screenshots go (default: ./kamoji-shots)
32
33
  --reboot restart Kamoji by itself when the app's Bluetooth services need it
33
- --app ID (logs) filter the USB log to this app
34
+ --app ID (logs) only this app's lines
34
35
  --verbose every USB log line, and more detail
35
36
  --no-lua don't run luac
36
37
  --json (check) print the result as JSON
37
38
 
38
- While "kamoji dev" runs: Enter = install again, o = open, s = screenshot, b = restart Kamoji, q = quit.
39
+ While "kamoji dev" runs (a save sends only the changed files; Enter sends every file):
40
+ Enter = install again, o = open, s = screenshot, b = restart Kamoji, q = quit.
39
41
 
40
42
  Before you start: disconnect the Kamoji app on your phone (Kamoji takes one Bluetooth connection at
41
43
  a time). The first time, keep the computer right next to Kamoji: it then trusts this computer (key in
@@ -45,6 +47,7 @@ const OPTIONS = {
45
47
  device: { type: 'string' },
46
48
  port: { type: 'string' },
47
49
  ble: { type: 'boolean' },
50
+ 'ble-logs': { type: 'boolean' },
48
51
  usb: { type: 'boolean' },
49
52
  out: { type: 'string' },
50
53
  reboot: { type: 'boolean' },
@@ -74,8 +77,10 @@ const keyStore = (board) => {
74
77
  return { key: k.key, created: k.created }
75
78
  }
76
79
 
80
+ export const NO_CABLE_BLE_LOG = 'No USB cable: the app log comes over Bluetooth (plug in a cable for crashes and resets).'
81
+
77
82
  /** The USB serial log, when there is (or must be) one. */
78
- async function openSerial(a, ui, onLine) {
83
+ async function openSerial(a, ui, onLine, { quiet = false } = {}) {
79
84
  if (a.ble) return null
80
85
  let port = a.port && a.port !== 'auto' ? a.port : null
81
86
  try {
@@ -89,7 +94,7 @@ async function openSerial(a, ui, onLine) {
89
94
  return null
90
95
  } else if (a.usb) throw new KamojiError('usb', 'No Kamoji on USB.', 'Plug it in with a USB-C data cable, or pass --port.')
91
96
  else {
92
- ui.info('No USB cable: no Kamoji log (plug it in for print() output, Lua errors and crashes).')
97
+ if (!quiet) ui.info(NO_CABLE_BLE_LOG)
93
98
  return null
94
99
  }
95
100
  }
@@ -158,7 +163,13 @@ export async function main(argv = process.argv.slice(2)) {
158
163
  keys: keyStore,
159
164
  reboot: !!a.reboot,
160
165
  lua: !a['no-lua'],
166
+ bleLogs: !!a['ble-logs'],
161
167
  })
168
+ // The app log over Bluetooth (firmware 0.3.3) when there is no USB log, or with --ble-logs.
169
+ const useSerial = async (onLine) => {
170
+ dev.serial = await openSerial(a, ui, onLine)
171
+ if (!dev.serial) dev.bleLogs = true
172
+ }
162
173
  const shotsDir = path.resolve(a.out ?? 'kamoji-shots')
163
174
  let code = 0
164
175
  const stop = async (c) => {
@@ -171,9 +182,16 @@ export async function main(argv = process.argv.slice(2)) {
171
182
  })
172
183
  try {
173
184
  if (cmd === 'logs') {
174
- if (a.ble) throw new KamojiError('usb', 'kamoji logs reads the USB log: drop --ble.')
175
185
  dev.appId = a.app ?? null
176
- dev.serial = await openSerial({ ...a, usb: true }, ui, (l) => dev.logLine(l))
186
+ dev.reopen = false
187
+ if (!a.ble) dev.serial = await openSerial(a, ui, (l) => dev.logLine(l), { quiet: true })
188
+ if (!dev.serial || a['ble-logs']) {
189
+ if (!dev.serial && !a.ble) ui.info('No USB cable: Kamoji\'s app log over Bluetooth (crashes and resets need the cable).')
190
+ dev.bleLogs = true
191
+ dev.watching = true // reconnect when the link drops
192
+ await dev.connect()
193
+ if (dev.notes.has('no-ble-log')) throw new KamojiError('unsupported', 'No log over Bluetooth on this firmware.', 'Plug in a USB-C data cable and run kamoji logs again.')
194
+ }
177
195
  if (!dev.appId && !a.verbose) ui.info('Showing app lines, errors and crashes; add --verbose for every line, --app <id> to follow one app.')
178
196
  await new Promise(() => undefined) // until Ctrl-C
179
197
  }
@@ -183,11 +201,11 @@ export async function main(argv = process.argv.slice(2)) {
183
201
  for (const app of list.apps)
184
202
  ui.info(
185
203
  `${app.ok ? `mode ${String(list.modes[app.id]).padEnd(3)}` : 'cannot run'} ${app.id} ${app.version} ${app.name}` +
186
- `${app.bytes !== undefined ? ` ${kb(app.bytes)}` : ''}${app.reason ? ` (${app.reason})` : ''}`,
204
+ `${app.bytes === null ? ' ? KB' : app.bytes !== undefined ? ` ${kb(app.bytes)}` : ''}${app.reason ? ` (${app.reason})` : ''}`,
187
205
  )
188
206
  if (!list.apps.length) ui.info('No mini apps on this Kamoji.')
189
207
  } else if (cmd === 'shot') {
190
- dev.serial = await openSerial(a, ui, () => undefined)
208
+ dev.serial = await openSerial(a, ui, () => undefined, { quiet: true })
191
209
  await dev.screenshot(shotsDir)
192
210
  } else if (cmd === 'forget') {
193
211
  await dev.connect()
@@ -196,11 +214,11 @@ export async function main(argv = process.argv.slice(2)) {
196
214
  deleteKey(dev.conn.board)
197
215
  ui.ok(left >= 0 ? `Kamoji forgot this computer (${left} trusted device(s) left); key deleted.` : 'Kamoji did not know this key; key deleted.')
198
216
  } else if (cmd === 'install' || (cmd === 'dev' && a.once)) {
199
- dev.serial = await openSerial(a, ui, (l) => dev.logLine(l))
217
+ await useSerial((l) => dev.logLine(l))
200
218
  code = (await dev.deploy({ force: true })) ? 0 : 1
201
- if (code === 0 && dev.serial) await new Promise((r) => setTimeout(r, 3000)) // the app's first log lines
219
+ if (code === 0 && (dev.serial || dev.logsOn !== null)) await new Promise((r) => setTimeout(r, 3000)) // the app's first log lines
202
220
  } else if (cmd === 'dev') {
203
- code = await watchLoop(dev, a, ui, folder, shotsDir)
221
+ code = await watchLoop(dev, a, ui, folder, shotsDir, useSerial)
204
222
  }
205
223
  } catch (e) {
206
224
  if (e instanceof KamojiError) ui.error(e.message, e.hint)
@@ -210,13 +228,16 @@ export async function main(argv = process.argv.slice(2)) {
210
228
  await stop(code)
211
229
  }
212
230
 
213
- async function watchLoop(dev, a, ui, folder, shotsDir) {
231
+ async function watchLoop(dev, a, ui, folder, shotsDir, useSerial) {
214
232
  const { Reloader, watchFolder } = await import('./watch.js')
215
233
  dev.watching = true
216
- dev.serial = await openSerial(a, ui, (l) => dev.logLine(l))
234
+ await useSerial((l) => dev.logLine(l))
235
+ let full = false
217
236
  const reload = new Reloader(async () => {
218
237
  try {
219
- await dev.deploy()
238
+ const all = full
239
+ full = false
240
+ await dev.deploy({ full: all })
220
241
  } catch (e) {
221
242
  if (e instanceof KamojiError) ui.error(e.message, e.hint)
222
243
  else ui.error(e?.message ?? String(e))
@@ -240,6 +261,7 @@ async function watchLoop(dev, a, ui, folder, shotsDir) {
240
261
  try {
241
262
  if (k === '' || k === 'r') {
242
263
  dev.lastHash = null
264
+ full = true // Enter: every file, not only the changed ones
243
265
  await reload.fire()
244
266
  } else if (k === 'o') {
245
267
  await dev.connect()
@@ -0,0 +1,112 @@
1
+ // Bytes without Node's Buffer, so the protocol core runs in a browser too (the web IDE on
2
+ // developer.kamoji.bot). Node's Buffer is a Uint8Array, so everything here takes Buffers as well.
3
+
4
+ const enc = new TextEncoder()
5
+ const dec = new TextDecoder()
6
+
7
+ /** @param {string} s @returns {Uint8Array} */
8
+ export const utf8 = (s) => enc.encode(s)
9
+ /** @param {Uint8Array} b @returns {string} */
10
+ export const fromUtf8 = (b) => dec.decode(b)
11
+
12
+ /** @param {Uint8Array} b @returns {string} lowercase hex */
13
+ export function toHex(b) {
14
+ let s = ''
15
+ for (let i = 0; i < b.length; i++) s += b[i].toString(16).padStart(2, '0')
16
+ return s
17
+ }
18
+
19
+ /** @param {string} hex @returns {Uint8Array} (stops at the first non-hex pair, like Buffer.from(hex, 'hex')) */
20
+ export function fromHex(hex) {
21
+ const out = new Uint8Array(Math.floor(hex.length / 2))
22
+ let n = 0
23
+ for (; n < out.length; n++) {
24
+ const v = parseInt(hex.substr(n * 2, 2), 16)
25
+ if (Number.isNaN(v) || !/^[0-9a-fA-F]{2}$/.test(hex.substr(n * 2, 2))) break
26
+ out[n] = v
27
+ }
28
+ return out.subarray(0, n)
29
+ }
30
+
31
+ /** @param {string} b64 @returns {Uint8Array} */
32
+ export function fromBase64(b64) {
33
+ const bin = atob(b64.replace(/[^A-Za-z0-9+/=]/g, ''))
34
+ const out = new Uint8Array(bin.length)
35
+ for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
36
+ return out
37
+ }
38
+
39
+ /** @param {Uint8Array[]} parts */
40
+ export function concat(parts) {
41
+ const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0))
42
+ let o = 0
43
+ for (const p of parts) {
44
+ out.set(p, o)
45
+ o += p.length
46
+ }
47
+ return out
48
+ }
49
+
50
+ // ------------------------------------------------------------------ MD5 (RFC 1321)
51
+ // The install protocol names every file by its md5; WebCrypto has no MD5.
52
+
53
+ const S = [7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20,
54
+ 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21]
55
+ const K = Array.from({ length: 64 }, (_, i) => Math.floor(Math.abs(Math.sin(i + 1)) * 2 ** 32) >>> 0)
56
+
57
+ /** @param {Uint8Array|string} input (a string is UTF-8) @returns {string} lowercase hex */
58
+ export function md5Hex(input) {
59
+ const data = typeof input === 'string' ? utf8(input) : input
60
+ const len = data.length
61
+ const padded = new Uint8Array(((len + 8) >>> 6 << 6) + 64)
62
+ padded.set(data)
63
+ padded[len] = 0x80
64
+ const dv = new DataView(padded.buffer)
65
+ dv.setUint32(padded.length - 8, (len * 8) >>> 0, true)
66
+ dv.setUint32(padded.length - 4, Math.floor(len / 0x20000000), true)
67
+ let a0 = 0x67452301
68
+ let b0 = 0xefcdab89
69
+ let c0 = 0x98badcfe
70
+ let d0 = 0x10325476
71
+ const M = new Uint32Array(16)
72
+ for (let off = 0; off < padded.length; off += 64) {
73
+ for (let i = 0; i < 16; i++) M[i] = dv.getUint32(off + i * 4, true)
74
+ let A = a0
75
+ let B = b0
76
+ let C = c0
77
+ let D = d0
78
+ for (let i = 0; i < 64; i++) {
79
+ let F
80
+ let g
81
+ if (i < 16) {
82
+ F = (B & C) | (~B & D)
83
+ g = i
84
+ } else if (i < 32) {
85
+ F = (D & B) | (~D & C)
86
+ g = (5 * i + 1) % 16
87
+ } else if (i < 48) {
88
+ F = B ^ C ^ D
89
+ g = (3 * i + 5) % 16
90
+ } else {
91
+ F = C ^ (B | ~D)
92
+ g = (7 * i) % 16
93
+ }
94
+ F = (F + A + K[i] + M[g]) >>> 0
95
+ A = D
96
+ D = C
97
+ C = B
98
+ B = (B + ((F << S[i]) | (F >>> (32 - S[i])))) >>> 0
99
+ }
100
+ a0 = (a0 + A) >>> 0
101
+ b0 = (b0 + B) >>> 0
102
+ c0 = (c0 + C) >>> 0
103
+ d0 = (d0 + D) >>> 0
104
+ }
105
+ const out = new Uint8Array(16)
106
+ const ov = new DataView(out.buffer)
107
+ ov.setUint32(0, a0, true)
108
+ ov.setUint32(4, b0, true)
109
+ ov.setUint32(8, c0, true)
110
+ ov.setUint32(12, d0, true)
111
+ return toHex(out)
112
+ }