Basil is an inventory management front-end for Grocy designed specifically for dedicated Android devices equipped with barcode reader hardware. While the official Grocy web interface is powerful, it can be cumbersome on small, industrial screens. By leveraging hardware scanner intents, the app doesn't need to initialize a camera or isolate rogue input from a keyboard or bluetooth device. It listens at the OS level, calls the Grocy API in realtime, and provides haptic feedback so you can keep your eyes on the physical stock.
- Purchase Mode: Quickly add items to your stock. Basil intelligently checks the product's Grocy product and only prompts for an expiration date if the item requires it or if a default shelf-life isn't set. A one-tap label print option is displayed after adding to stock.
- Consume Mode: Simply scan to remove from stock. Basil follows your Grocy instance's transaction logic to ensure virtual inventory matches physical reality.
- Inventory Lookup: Instantly view a details of items in stock including specific expiration dates and quantities for each.
- Grocy-First: Basil first checks your Grocy database for the barcode.
- OpenFoodFacts-Fallback: If unknown, it triggers a lookup with OpenFoodFacts via Grocy's API.
- User Defaults: Newly discovered items are automatically assigned to the Default Location (configured in Grocy User Settings of the user the API key is associated with), preventing the "Missing Location" errors common in other apps.
- Gemini AI Enrichment: If enabled, Gemini AI can determine estimated item cost, due dates, and storage location based upon the product name identified.
- Deep Purple UI: High-contrast, dark-themed interface designed to elimninate need for light/dark selection, reduce visual strain, and look sleek on industrial displays.
- Haptic Language:
- Short Pulse: Success / Scan Accepted.
- Double Pulse: Error / Item Not Found.
- Triple Pulse: Input Required (e.g., Expiration Date needed).
| Grocy Config | Gemini Enable | Gemini Config | Settings |
|---|---|---|---|
 |
 |
 |
 |
| Purchase Scan | Purchase Success | Inventory Example 1 | Inventory Example 2 |
|---|---|---|---|
 |
 |
 |
 |
Basil uses a zero-config setup. Generate an API key in Grocy and show the QR code to scan in Basil.
You could also generate your own if desired using format: Grocy URL and API Key separated by a pipe (|): https://grocy.yourdomain.com/api|your_secret_api_key_here
💡 In environments where you may share the scanner device with multiple people, it may be desireable to create a generic "Basil" user (or the name of your chosing) in Grocy for the device and create the API key attached to that user account. Thus the journals will show "Basil" vs. an indiviuals name who may not have been using the shared device.
For the hardware buttons to work, configure your PDA's "Scanner" or "DataWedge" to output the following:
- Intent Action:
com.basil.grocyscanner.SCAN - Intent Delivery:
Broadcast Intent - String Extra:
barcode_dataOutput the complete UPC including check digit. NO spaces or other formatting prefix/suffix.
💡 You may want to disable other types of barcode formats to eliminate 'false scans'. Many products have Datamatrix/QR Code on the packaging for consumer and non-consumer purpoposes. However, if you are using Grocycode or custom printed Datamatrix/QR Code labels, make sure those formats are not disabled. Basil can process them!
Basil is built using modern Android standards to ensure long-term maintainability:
- Language: Kotlin 2.x
- UI Framework: Jetpack Compose (Declarative UI)
- Networking: Retrofit 2 + OkHttp 4
- JSON Parsing: Gson
- Async Logic: Kotlin Coroutines & Flow
- Architecture: MVVM (Model-View-ViewModel)
Basil communicates with the Grocy REST API. Key endpoints include:
/stock/products/by-barcode/{barcode}: Primary resolution./stock/barcodes/external-lookup/{barcode}?add=true: The "magic" auto-add trigger./stock/products/{productId}/entries: Powers the Inventory table.
Basil is open-source because the self-hosting community thrives on shared tools.
- Fork the repository.
- Create a feature branch (
git checkout -b feature/AmazingFeature). - Commit your changes (
git commit -m 'Add some AmazingFeature'). - Push to the branch (
git push origin feature/AmazingFeature). - Open a Pull Request.
Distributed under the MIT License. See LICENSE for more information.
Developed with ❤️ in Massachusetts by Justin Sabourin for the Grocy Community.