Skip to main content

Channels

Channels manages TV channel lineups for cable, satellite, and IPTV sources. Channel lineups provide user-friendly channel selection with logos, names, and favorites.

Overview​

The Channels feature provides:

  • Channel Providers: Manage different channel sources (cable, satellite, IPTV)
  • Channel Lineups: Define available channels with logos and metadata
  • External Sync: Sync channel data from external sources
  • Favorites: Mark frequently-watched channels
  • Channel Logos: Display network logos in UIs

Viewing Channels​

The main grid displays channels filtered by provider:

Columns​

  • ID - Unique channel identifier
  • Channel - Channel number (2, 5, 48, 501, etc.)
  • Name - Channel name (ABC, ESPN, HBO, etc.)
  • Logo - Logo image URL or path
  • Call Sign - Station call sign (WABC, KABC, etc.)
  • Favorite - Favorite status
  • Enabled - Whether channel is available
  • Sort Index - Display order

Grid Actions​

  • Add - Create a new channel manually
  • Delete - Remove a channel
  • Sort - Reorder channels

Channel Providers​

Channel providers represent different channel sources:

Provider Selector​

Dropdown at top of page:

  • Select provider to view/edit its channels
  • Each provider has independent channel lineup

Actions:

  • New - Create a new provider
  • Edit - Modify selected provider
  • Sync - Sync channels from external source

Creating a Provider​

Click New button:

Configuration:

Name: Internal identifier (auto-formatted to lowercase_with_underscores)

  • Examples: cable_comcast, satellite_directv, iptv_stream

External Provider ID: Identifier for external sync service (optional)

  • Used when syncing channels from an external API
  • Provider-specific ID from the external service
  • Example: Comcast system ID, DirecTV location code
  • The Sync button is only enabled when this field is set

Editing a Provider​

  1. Select provider from dropdown
  2. Click Edit button
  3. Modify configuration
  4. Click Save

Changes affect:

  • Provider metadata
  • Sync settings
  • All channels in lineup

Syncing Channels​

External Channel Sync​

The Sync button synchronizes channel data from external sources:

When to Sync:

  • Initial setup (populate channel lineup)
  • Channel lineup changes (new channels added by provider)
  • Channel number changes
  • Logo updates

Sync Process:

  1. Select provider from dropdown
  2. Click Sync button
  3. GEM contacts external service (if external_id configured)
  4. Downloads current channel lineup
  5. Updates/adds channels:
    • New channels added
    • Existing channels updated
    • Removed channels flagged
  6. Success message shows results

External Sources:

  • Provider APIs (if available)
  • EPG (Electronic Program Guide) services
  • Third-party channel databases
  • Custom integrations

Requirements:

  • Provider must have external_id configured
  • Network connectivity to sync service
  • Valid API credentials (if required)

Manual Channel Entry​

For providers without sync support:

  1. Select provider

  2. Click Add to create channel

  3. Enter channel details:

    Channel: Channel number

    • Example: 2, 5, 48, 501

    Name: Channel name

    • Example: "ABC", "ESPN", "HBO"

    Logo: Logo image URL or path

    • Example: https://logo.provider.com/abc.png
    • Or: /images/logos/abc.png

    Call Sign: Station identifier

    • Example: "WABC-DT", "ESPN-HD"

    Favorite: Check if favorite channel

    Enabled: Check to make available

    Sort Index: Display order — set manually, or drag rows in the grid and click the Save Sort Order button (swap-sort icon) in the toolbar

  4. Click Save

Using Channels in UIs​

Channel Selection​

When broadcast source selected (cable, satellite):

UI Displays:

  • Channel grid or list
  • Channel logos
  • Channel numbers and names
  • Favorites section (if favorites configured)

User Actions:

  • Click channel to tune
  • Search by name or number
  • Browse by category (news, sports, movies)
  • Access favorites quickly

Channel Commands​

Selecting a channel sends command to source device:

Command Format:

Device: cable_box
Command: channel
Args: {channel: 501}

Device driver translates to device-specific protocol:

  • Direct tune: CHAN0501
  • IR codes: Individual digit commands
  • IP control: API channel change

Preset Enter Behavior​

When tuning channels via individual digit commands (IR codes), GEM sends each digit to the device and then automatically sends an enter or select command to confirm the channel. Some devices auto-tune after the last digit and do not require this confirmation.

To disable the automatic enter command for a device, set the preset_enter attribute to false on the device in Devices > Attributes.

Preset Padding​

Some devices require channel numbers to be zero-padded to a fixed width (e.g., channel 5 sent as 005). Set the preset_padding attribute on the device to the desired number of digits. When preset padding is set, the enter/select command is automatically skipped since the device knows the channel is complete once all digits are received.

Related device attributes:

  • preset_enter - Set to false to skip the enter/select command after channel digits (default: true)
  • preset_padding - Zero-pad channel numbers to this many digits (e.g., 3 sends channel 5 as 005). Automatically skips the enter command when set.
  • channel_enter_delay - Delay in milliseconds before sending the enter command (overrides the default digit speed)

Favorite Channels​

Marking Favorites​

In channel grid:

  • Check Favorite column for frequently-watched channels
  • Or in UI, long-press channel to mark favorite

Favorite Display​

UIs can show favorites prominently:

  • Separate favorites section
  • Quick access buttons
  • First in channel lists

Use Cases​

Sports Fans: Favorite all sports channels News Watchers: Favorite news channels Kids: Favorite children's channels (parental control)

Channel Logos​

Automatic Logo Fetching​

Some device drivers automatically fetch and cache channel logos. For example, the Apple TV driver retrieves app icons from the App Store when syncing its app list as channels. Icons are cached locally in /images/icons/<device_name>/ and assigned to channels automatically — no manual logo configuration is needed.

Logo Sources​

External URLs:

https://cdn.example.com/logos/abc.png
https://logo-service.com/v1/channels/501.png

Local Files:

/images/channel_logos/abc.png
/static/logos/espn.png

Theme Assets:

/themes/carbon/icons/channels/hbo.png

Logo Requirements​

  • Format: PNG (transparent background) or JPG
  • Size: 128x128 to 256x256 pixels
  • Aspect Ratio: Square or channel logo aspect ratio
  • File Size: < 100KB for fast loading

Uploading Logos​

Option 1: Upload to static directory

scp channel_logos/*.png gem-server:/opt/gem/static/images/logos/

Option 2: Reference external CDN

  • Use provider's logo CDN
  • Or third-party logo service

Option 3: Theme assets

  • Upload via UI Themes page
  • Store in theme for portability

Channel Organization​

Sorting Channels​

By Channel Number (default):

  • 2, 3, 4, 5, ... 48, 49, 50
  • Matches remote control channel up/down
  • Most intuitive for users

By Name:

  • ABC, CBS, CNN, ESPN, HBO, ...
  • Alphabetical browsing

By Category:

  • News channels together
  • Sports channels together
  • Movies channels together
  • Requires category attribute

Custom Order:

  • Use sort index to create custom order
  • Favorites first, then by number
  • Most-watched first

Advanced Topics​

Multi-Provider Support​

Different providers for different zones:

Example:

Living Room: Comcast Cable (provider_id: 1)
Bedroom: DirecTV Satellite (provider_id: 2)
Guest House: IPTV Stream (provider_id: 3)

Each AV zone can use a different provider:

  • Configure in AV source
  • Source links to provider
  • Channel selection uses appropriate lineup

EPG Integration​

Electronic Program Guide integration:

Store in Attributes:

channel_id: 501
epg_data: {
  current_show: "Evening News",
  current_time: "18:00-19:00",
  next_show: "Primetime Game",
  description: "Local and national news coverage"
}

Display in UI:

  • Show what's on now
  • Show what's on next
  • Full program schedule

Sync:

  • Periodic updates from EPG service
  • Store in channel attributes
  • Expire old data

Channel Categories​

Organize channels by category:

Implementation via Attributes:

// On each channel
category: "sports"  // or "news", "movies", "kids", etc.

UI Benefits:

  • Filter channels by category
  • Browse by genre
  • Category headers in channel list

Parental Controls​

Restrict channels based on rating:

Channel Attributes:

rating: "TV-MA"  // TV-Y, TV-PG, TV-14, TV-MA
adult_content: true

User/Role Attributes:

max_rating: "TV-PG"
block_adult: true

Implementation:

  • Filter channels in UI based on user role
  • Require PIN for restricted channels
  • Hide adult channels from kids' profiles

Channel Remapping​

When provider changes channel numbers:

Update Channels:

  1. Run sync (if supported)
  2. Or manually update channel numbers in grid
  3. Changes reflect immediately in UIs

Macro Channel References:

  • Use channel name instead of number for robustness
  • "Tune to ESPN" instead of "Tune to 501"
  • Survives channel number changes

Troubleshooting​

Channels Not Displaying​

Check:

  1. Provider Selected: Provider chosen in dropdown
  2. Provider Enabled: Provider is enabled
  3. Channels Exist: Provider has channels configured
  4. Grid Filter: Grid may be filtered
  5. Browser Cache: Refresh page

Sync Failed​

Check:

  1. External ID: Provider has external_id configured
  2. Network: GEM can reach sync service
  3. Credentials: API credentials valid (if required)
  4. Service Status: Sync service online and working
  5. Logs: Check for sync error details

Channel Logos Not Showing​

Check:

  1. Logo URL: URL is valid and accessible
  2. File Exists: Logo file exists at path
  3. Permissions: GEM can read logo file
  4. Format: Logo is PNG or JPG
  5. CORS: External URLs allow cross-origin (if applicable)

Wrong Channels Tuning​

Check:

  1. Channel Number: Correct channel number in database
  2. Device Commands: Device accepts channel commands
  3. Command Format: Channel command format correct for device
  4. Provider Match: Using correct provider for source

Cannot Delete Channel​

Check:

  1. References: Channel may be referenced in macros
  2. Favorites: Remove from favorites first
  3. Provider: Verify correct provider selected

Best Practices​

  1. Sync Regularly: Run sync monthly or when lineup changes

  2. Favorites: Pre-configure favorites for common channels

  3. Logos: Use high-quality logos for professional appearance

  4. Sorting: Choose sort method that matches user expectations

  5. Categories: Organize large lineups (>100 channels) with categories

  6. Testing: Test channel tuning after sync

  7. Documentation: Document provider credentials and sync process

  8. Backup: Export channel data before major changes